Using a Custom Tool of a Previous Version

The interface for the tool development has changed since MERLIC 5.1. Because of some of these changes, existing custom tools that have been created for MERLIC 5.1. or a previous MERLIC version might require some adjustments in order to use these tools in MERLIC 5.6.2.

In the following, we describe in more detail which custom tools require an update and give information how to perform this update.

Which Custom Tools Require an Update?

An existing custom tool must be updated for the use in MERLIC 5.6.2 if the following conditions apply:

• The custom tool was created originally for the usage in a MERLIC version 4.0 to 5.1.0.
• The HDevelop procedure library of the custom tool contains an "_Info" procedure.
• The interface procedures Me_add_roi_support_* are used in the custom tool implementation.

In case your custom tool contains a Quick Info documentation, you have to recreate the Quick Info in a new format according to the new tool development interface. Otherwise, it will not be available when using the custom tool in MERLIC 5.6.2.

Changes of the Tool Development Interface

In the following, we want to give a short overview of the changes at the tool development interface that make it necessary to update existing custom tools.

"ToolHandle" Parameter

The "ToolHandle" parameter has been removed from the _Info procedure as well as from the following interface procedures:

• Me_add_roi_support_all
• Me_add_roi_support_circle
• Me_add_roi_support_paraxial_rect
• Me_add_roi_support_point
• Me_add_roi_support_rectangle
• Me_add_roi_support_segment

Therefore, all existing custom tools that make use of these procedures need to be updated to remove the "ToolHandle" parameter. This can be done with the Python script "ConvertTool.py" that is provided with the MERLIC installation.

Unsupported Interface Procedures

In the current interface for the tool development, some of the interface procedures that were previously provided are not supported anymore.

• Me_convert_from_encoding_to_utf8
• Me_quickinfo
• Me_set_drawing_linestyle
• Me_set_drawing_linewidth
• Me_set_drawing_mode
• Me_set_drawing_style
• Me_set_font
• Me_set_font_color

The provided Python script "ConvertTool.py" also checks whether any of these procedures is used in the HDevelop procedure library of the custom tool. If any of these procedures is found, the respective procedure calls are deactivated.

Quick Info Documentation

The concept of integrating a Quick Info documentation for a custom tool has changed. Previously, the documentation for the Quick Info had to be defined in the procedure settings of the tools' main procedure. Now, the documentation must be provided in a separate HTML file and it must be stored at a specific location with a predefined structure. One of the advantages of the new concept is that you can provide a Quick Info in all languages in which MERLIC is available instead of only in English as for the previous tool development interface.

If the Quick Info of an existing custom tool is not updated to the new concept, the tool can still be loaded in MERLIC but no Quick Info documentation will be visible in the tool board. The adjustment of the Quick Info must be done manually. For more information about how to add a Quick Info for a custom tool in MERLIC 5.6.2 and the required file structure, see the topic Adding a Quick Info for a Custom Tool.

Converting Custom Tools of Previous Versions

MERLIC provides the Python script "ConvertTool.py" to convert a custom MERLIC tool of a previous version for the use in the current MERLIC version. As described above, the conversion is required if the tool was created originally for the usage in a MERLIC version 4.0 to 5.1.0, if the tool contains an "_Info" procedure, and if the tool uses the interface procedures for the ROI support, i.e., Me_add_roi_support_*.

The script performs the following changes in the tool:

• It removes the "ToolHandle" parameter from the "_Info" procedure of the custom tool.
• It removes the "ToolHandle" parameter from all Me_add_roi_support_* procedures.
• It deactivates all procedure calls to unsupported interface procedures.

When converting a custom tool, a backup file of the original custom tool will be created in the specified path.

Location

You can find the script in the following directory within the MERLIC installation: "\examples\tool_development\convert_tools".

To convert a custom tool, open a command prompt in the directory of the Python script, and start the script as described below. If you start the script from a different location, make sure to add the path to the script when calling the command.

Converting a Single Custom Tool

To convert a single custom tool, use the command line option "-f" and add the path and file name of the custom tool, e.g., the respective HDevelop procedure library (.hdpl).

python.exe ConvertTool.py -f <PATH_TO_CUSTOM_TOOL\FILE_NAME>

Converting Multiple Custom Tools

To convert all custom tools at a specific location, use the command line option "-p" and add the path of the directory in which the custom tools are located.

python.exe ConvertTool.py -p <PATH_TO_CUSTOM_TOOLS>

All custom tools with the file format .hdpl, .mvtool, and .hdvp in the given location will be converted.