Release Notes R3.8

Introduction

Release 3.8 is issued by Institute for Energy Technology in January 2012.

Questions, bug reports, and requests for changes or new functions, should be directed by email to procsee-support@hrp.no

A ProcSee interest group mailing list has been established. Messages from the development team of general interest to ProcSee users are sent there. Everyone developing software with ProcSee is encouraged to join the interest group to keep up-to-date with new versions and future plans. To join the interest group, send an email to procsee-support@hrp.no.

Supported Platforms

The following platforms are supported:

For the Linux and Apple Mac platforms, ProcSee requires additional runtime libraries to be installed. For details, please refer to the ProcSee download page on the web.

Compatibility With Previous Versions

ProcSee 3.8 uses SWBus version 4.9 as its basic communication system, and the internal message protocol is unchanged. In general ProcSee 3.8 is compatible with version 3.7. However, note the following modifications:

• Two new APIs are introduced in this version. Therefore, we have also renamed the libraries for the existing C/C++ API from p3 to ProcSeeApiC. Refer to the first page of the API Manual pages in the Reference Manual for details on the file names.
• Due to the introduction of the new Display object type, a number of functions to convert between different coordinate systems have been marked deprecated. These functions continue to function properly for existing application, but will fail if used together with the new feature to scale an entire application. Using the deprecated functions issues a warning in the RTM's output window. The new function xyConv replaces all these functions and should be used when the scaling features of the new Display object are used.
• Due to the introduction of the new Display object type, the behaviour of the pTALK functions shapeCursorX and shapeCursorY has changed. Existing applications must add the argument "xyOld" everywhere these functions are used for primitive shapes (i.e. shapes other than instances and trends) to ensure the application will continue to work as before.
• The definition of a window's position and size was different on the Windows platform compared to the Linux, Unix and Mac platforms. Now these definitions are identical on all platforms and consistent with the previous definition on the Windows platform. A Window's position is defined as the upper left corner of the window, inside the window frame. The width and height also excludes the frame.
• An unfortunate concequence of introducing the new object data types Point, Rect, Size, Vector, and Display, is that users who have used these names in their applications will have to change these names in their applications.
• The checking of the format string of text-shapes and printf/sprintf arguments has been improved and now provides better feedback on errors. Note specifically that previous versions incorrectly accepted format-strings like "%d%", and displayed e.g. 12% on the screen. The new version will issue an error message and display 12??? on the screen. The correct format-string for this example is "%d%%".
• The pTALK function update now includes updating the resources.
• The order of the elements within a Tdoc file has been changed to reduce the likelihood of elements being referenced before being defined. The use of comments in Tdoc files has also changed, ref separate item below.

Improvements and New Features

New APIs, supporting more programming languages

The new version includes two new APIs. These APIs enable connecting external applications written in Java, C# and Managed C++ to the ProcSee RTM. The APIs include all the main features from the traditional API for C/C++ and are designed to be compliant with the normal programming styles of these languages.

Documentation for direct integration with the developers Integrated Development Environment (IDE) is provided in the form of XML Documentation for the .NET API and JavaDoc for the Java API. This enables documentation assistance as you type, alongside code auto completion. Visual Studio will use the XML documentation automatically, whilst the Java IDEs require you to specify the JavaDoc-folder at the same time you add the ProcSee Java library into your project.

Two new tutorials have been developed, giving the user a hands-on experience on how to develop external applications for ProcSee using the Java API or the .NET API. The new tutorials are based on the new Ketchup factory demo application.

New object types: Display, DisplayInfo and DisplayInfoSet

The Display object represents a display surface where the RTM can display its windows. It can be a physical monitor, a virtual display or an area on a display. Using the Display object, the application developer can easily resize the application to fit whatever monitor size the end user actually uses. Modifying a Display object's attributes affects the size and position of all windows referring to the Display object. By default, all applications will have one Display object and all windows will by default
refer to this Display object. The user may create additional Display objects using GED or the pTALK function newDisplay.

The DisplayInfo class provides methods to query for properties and capabilities of a display. These include width and height, number of colour planes and more. The DisplayInfoSet class stores a collection of DisplayInfo objects. To access the global set of all displayInfo objects, use the syntax DisplayInfoSet* dsi = DisplayInfoSet.get("*");

Refer to section 9.11 in the User's Guide for details on how to configure the Display object settings from GED and to the Reference Manual for details on how to use these new object types from pTALK. The ProcSee demo application can be used as an example on how to implement applications enabling the end-user to resize the top-level window freely and have the application respond properly by scaling to fit the windows' size.

Transparent colours

ProcSee now supports transparent colours. The degree of transparency can be controlled from GED's colour editor, using the pTALK functions Colour::setTransparency and Colour::getTransparency, or in the Tdoc file.

Editing individual shapes of groups or trends

Users may now edit the individual shapes of groups and trends directly in GED. Double-clicking the group or trend will enable the editing of the individual shapes, pressing the Esc-button will return to normal. Transparent colours are used to inform the user which objects are available for editing. This way of editing also works for nested objects like groups within groups or trends within groups. Double-click to enter into editing at the next level, press Esc to go one level out.

Active shapes and layers

Active shapes and layers is an editing feature used by GED, it has no effects when the end-user operates the displays. While editing a picture or class, the designer can create sets of shapes, and these sets can be activated or deactivated independently. Layers can also be activated or deactivated. Shapes in inactive sets or layers are visualised using semi-transparent colours.

The active shapes and layers feature is useful for example to prevent the designer from accidentally editing or moving some shapes or to prevent certain shapes from being included in a selection. The shape sets are persistent, i.e. stored to file and recreated next time the picture is loaded.

The dialog to control the active shapes and layers feature is available from the toolbar (Active Shapes & Layers button) and from the View-menu in GED's drawing editor. Refer to section 13.4 of the User's Guide for details on the dialog.

Function to find dependencies

The new pTALK function getDependencies returns a list of objects that a specific object depends on. Typically, the function can be used to list all variables referenced from the dynamics of a picture. How and what to search for can be specified using the function's optional flags argument.

Enhanced format specifiers for Text and printf/sprintf

The format specifiers for Text shape and pTALK functions printf and sprintf have been extended to support new features like: thousand separator, number of digits to use for E-notation, output of binary numbers, and more. Refer to the Reference Manual for details.

New functions strformat and strcftime

A new pTALK function, strformat, operates like sprintf but allocates the buffer needed for the converted string automatically, making it very convenient to use. In the same way, a new pTALK function, strcftime, operates like cftime but automatically allocates the buffer. The fact that the RTM uses reference counting and automatically frees any character string no longer in use makes these functions even more convenient.

A standardized function to convert between coordinate systems, xyConv

There are a number of pTALK functions to convert from one coordinate system to another. A new function, xyConv, can convert between any combinations of coordinate systems, making it the preferred function for any conversion. Refer to the Reference Manual for details about this function and a detailed description of the various coordinate systems. Warnings from deprecated conversion functions can be omitted by using the function xyConv instead.

getList supports filtering on names and searching for sub-shapes

The pTALK function getList now accepts name='someValue' in its flags-argument to search for objects matching a specified name. Note that the value can include the wildcard characters * and ?. The search is by default case-sensitive, but may be specified case-insensitive. Refer to the Reference Manual for details.

Pragma Directives in pdat files and new API functions

Pragma directives can now be used in pdat files. Syntax and available options are described in "The ProcSee database file format" part of the Reference Manual. Current options include controls for whether variable updates should be sent from the RTM to external applications, and whether string (i.e. char*) variables and struct fields should be transferred between external applications and the RTM. Note that the pragma directive enables these settings to be controlled for individual sets of variables.

Two new API functions, PfSendApiStringUpdates and PfReceiveRtmStringUpdates, have been introduced to enable and disable transfer of string values between external applications and the RTM. By default, string values are not transferred.

update-function

The pTALK function update now takes two optional arguments. The first argument is the object to update, the second argument is a flag specifying whether the update should be synchronous or asynchronous. If no arguments are supplied, the RTM will perform a global asynchronous update, i.e. update all visible objects of all open applications.

Note that multiple asynchronous updates do not hurt performance, as asynchronous updates are put on a queue and multiple updates are merged into one when extracted from the queue. Synchronous updates on the other hand should be used with care as they are executed immediately and thereby may harm overall system performance.

Improved infrastructure to analyse and track down crash-problems

For the new version we have established an infrastructure for handling dump files of ProcSee executables. The dump files are generated by Microsoft Windows in the event of a program crash, and the information in these files can assist the ProcSee development team to analyse and track down the problem. The ProcSee installer enables dump file generation under Windows Server 2008, Windows Vista with Service Pack 1, and later versions. By default the dump files are stored in the folder: %LocalAppData%\CrashDumps. This folder may contain dump files from other programs and the relevant files for ProcSee starts with rtm.exe or ged.exe. In case you experience a program crash and report it to ProcSee support, we kindly ask you to send the dump file to help us solve the problem.

New object types: Point, Size and Rect

Object types Point, Size and Rect have been defined. A Point objects holds a position, i.e. attributes x and y. A Size object holds a size, i.e. attributes width and height. A Rect object holds the position and size of a rectangular area, i.e. attributes x, y, width and height.

All of these object types have a set-function to set all its attributes in a single operation.

In addition we have added Vector as an empty type, just to reserve this name for future implementation.

Other improvements

• Error messages produced to the RTM's output window in the case of failing pTALK code have been significantly improved when it comes to pinpointing the correct stack-trace. This should help developers to more easily identify the cause of the problem.
• A new pTALK function, nameOf, have been added. The function takes a pointer argument and returns the name of whatever object the pointer points to, similar to the existing function fullNameOf.
• Comments can now be saved and loaded together with objects. Comments appear in the Tdoc file format, and can be accessed from pTALK using the functions setComment, getComment and searchComments.
• The connection between library layers and application layers can now be set from GED on Windows.  Refer to section 9.12 of the User's Guide for details.
• Using incompatible versions of GED and RTM now makes GED display a warning dialog about the possibly unstable combination.

Bugs fixed

• The default number of digits used for the exponent when presenting floating point numbers on the standard E-notation (i.e. as 1.23 E04) has been reduced from three to two.
• Alignment of texts aligning to their decimal point failed if the format-string included a digit.
• Error-objects were lost when saving a picture. Now error-objects are saved correctly to enable the developer to fix the problem.
• Loading an image from a non-existing file name caused the RTM to crash. Now it displays a text at the image's location stating a reason for the problem.
• Incorrect calculation in pTALK function Trend::xW2Time.
• Pointers to anonymous objects were saved to Tdoc file in an incorrect format.
• The implementation for the trend's scroll attribute did not comply with the documented behavior.
• Reusing a char array as first argument to function Hashtable::put lead to problems as the RTM used the array address for the key. Now HashTable::put copies the string and stores a pointer to the local copy.
• In the API, if a connection to an RTM was broken before the onConnect callback had been invoked, the RTM's id was not removed from the queue of processes waiting for their connect callback to be invoked. Further, the user's onDisconnect callback was activated even though the onConnect callback had not yet been activated. Now, neither the onConnect nor the onDisconnect callback will be invoked in such a case.
• Menu windows could sometimes hide behind their parents
• Incorrect behaviour of tool windows on the Linux/Unix platform
• Incorrect drawing of ellipsis if xRadius or yRadius was 0
• Failed to update text objects properly if format-attribute referenced a pointer that was deleted and recreated
• Arrays with large number of entries were garbled in GED if opened in the attribute editor
• Loading an application or library with a class name defined twice made the RTM crash. Now, the RTM warns when encountering the second definition and renames the class
• Incorrect drawing of gradients when a shape is rotated and its width or height is small
• Gradients were not updated if a colour used by a gradient was updated
• Picture backgrounds were incorrectly redrawn for autoscaled pictures after enlarging the window
• Inconsistent coordinate system definitions for primitive shapes compared to instances and trends
• In GED, text shapes contained in a group did not move correctly if the group was moved using the keyboard's arrow keys
• TimerInterval objects looped forever if interval was set to 0
• GED's undo/redo lists did not correctly present the editing operations

A number of other minor errors identified by the development team have also been corrected.