TRIUMF EdlBuild - Perl library for building EPICS edm screens

EdlBuild - a Perl Library for Building edl Input Files for the EPICS edm Display Manager

Copyright (c) TRIUMF 2005, ...
Version 1.0 - production version	for edm up to 1-11-0f
	Rolf Keitel, 2006/06/16:	fixed typo in programming example
	Rolf Keitel, 2006/08/03:	added fix... scripts to the tadl2edl part
	Rolf Keitel, 2006/10/05:	fixed a typo in triumfSlider.pm, added more fix.. scripts
Version 1-11-0p	production version for edm up to 1-11-0p
	Rolf Keitel, 2006/11/01:	added support for new properties of edm-1-11-0p added check tool (checkEdlModules.pl)

In case of discrepancies between this documentation and documentation in the source code, the source code is (probably) more correct.

Table of Contents

Introduction
Programming Example
Technical Details
Download and Installation
Site-Specific Configuration
Adding Support for New edm Widgets
Checking for Consistency
Limitations and Known Problems

Introduction

EdlBuild is a collection of Perl modules, which provide a programming interface for generating edl files from Perl scripts. It allows full configuration of every name/value pair of widget properties for all edm widgets. (It actually allows configuration of stuff, which had better not be changed. Suit yourself!).
EdlBuild is extensible and can easily accommodate new widgets as they are developed.

Programming Example

The following examplePerl script shows how to use EdlBuild. It should be self-explanatory to anyone with some knowledge of the Perl language:

#!/usr/bin/perl -w
#
# EdlBuild.pl
#
#
#======================================================================
#
use strict;

# environment variable EDLBUILD contains location of perl modules
use lib $ENV{EDLBUILD};
use Edl;

# get file name from command line
my $file = shift;
if (!defined $file) {
    $file = 'test';
}
# set up new edl file and return handle
my $edl = new Edl($file.'.edl');

# add some widgets
$edl->text_update(x => 300, y => 350, h => 50, w => 200, controlPv => '"$(D):VOL"');

$edl->reg_text_update(x => 300, y => 400, h => 50, w => 200, controlPv => '"$(D):VOL"');

$edl->text_entry(x => 600, y => 900, w => 200, controlPv => '"$(D):VOL"',
    font => '"helvetica-bold-r-12.0"');

$edl->choice_button(x => 600, y => 400, w => 200, controlPv => '"$(D):VOL"');

$edl->lines(x => 10, y => 500, h =>150, w => 200,
    xPoints => '0 10|1 120|2 10|3 120', yPoints => '0 500|1 520|2 530|3 540', numPoints => 4,
    lineWidth => 3);

# configure the final screen size
$edl->configure(w => 900, h=> 1100);

# finish up and write output file
$edl->finish();

top

Widget Generator functions

Graphics	Monitors	Controllers
arc	bar	button
circle	byte	choice_button
dynamic_symbol	meter	exit_button
embedded_window	msg_box	menu_button
gif_image	pv_inspector	menu_mux
lines	reg_text_update	message_button
png_image	strip_chart	motif_slider
static_text	symbol	radio_box
text_with_regexp	table	related_display
.	text_monitor	shell_command
.	text_update	slider
.	xy_graph	text_control
.	.	text_entry
.	.	updown_button

Technical Details - the Entrance to Code-Heaven

EdlBuild is a collection of Perl modules. Each widget is implemented as a Perl object.
EdlBuild uses the environment variable EDLBUILD to locate its modules, e.g. for csh

setenv EDLBUILD /usr/local/perllib/

The library consists of:

Edl.pm	common module, to be included with a "use" statement in the user's build script
EdlHead.pm	module to generate the edl file header
EdlDefaults.pm	module for site-specific configuration
Edl....pm	one Perl module Edl... for each edm widget

Widget Modules
Each widget module contains a template list of widget properties as they appear in the edl file followed by code which is identical for each widget.

Convention used for widget templates:
optional parameters can be added into the widget template with (a) or without (b) a leading | (vertical bar)
In case (a), the parameter is omitted from the edl file, if it is not specified at widget definition or configured later.
In case (b), the parameter is entered into the edl file as specified in the template, but may be overridden at widget definition or configured later.

The Common Module Edl.pm
This module contains

a "use" statement for each widget module
a generation function for each widget. The argument to this is a hash of key/value pairs, which override the widget properties in the template of the corresponding widget module.
common functions used by each widget module:

makeDefaultData() to parse the widget template
substituteParameters() for property substitution at widget generation
configureWidget() for property substitution at later time

Conventions for list properties
List properties, such as xPoints for the Lines widget, are passed as a single string value in a key/value pair. The individual list elements are separated by |.
Example:
$edl->lines(x => 10, y => 500, h =>150, w => 200,
xPoints => '0 10|1 120|2 10|3 120', yPoints => '0 500|1 520|2 530|3 540', numPoints => 4,
lineWidth => 3);

default configuration variables
can be overridden in EdlDefaults.pm

top

Download and Installation

Contents of tar file:

a) EdlBuild related files (supported by R.Keitel )

Edl.pm	main module
Edl<widget>.pm	complete set of widget modules

EdlCp.pm, EdlPanels.pm, EdlPanels2.pm	"Convenience" functions, used at TRIUMF for display building (not part of EdlBuild)

b) tadl2edl related files (provided "as-is")

tadl2edl.pl	a converter from edd/dm to edm format (adapted from the SLAC version for TRIUMF use, using the EdlBuild p\Perl modules). This converter is provided "as-is". It is developed solely for TRIUMF use. No bug-fix requests will be accepted for this tool.
tadl2edlClrSupport.pl	support for colour
badlfish....pl modules	TRIUMF versions of the SLAC badlfish suite.
colors.list calc.list	examples of TRIUMF files which implement dm-compatible colour rules
isacClrLut	example of a colour lookup-table used by tadl2edl to convert edd/dm colour indices to edm colour indices
usebadlfish	environment variable setup for tadl2edl
adl2edls.pl	converts all .adl files of a directory
fix*.pl	a set of perl filters, which fix some conversion weaknesses (inspect before using)

Not much to it:

Download the tar-ball and the example script from here
Extract the perl modules with the tar -xvf command to <wherever you like>
set the environment variable EDLBUILD, e.g. for csh: setenv EDLBUILD <wherever you like>
run the example script. edl files will be generated in your current directory

top

Site-Specific Configuration

The widget templates in the individual widget modules are preset with default property values and can be modified to reflect site-specific standards.
Default values for a few frequently used properties (indices for background, foreground, topShadow, botShadow, inconsistent, on, off colours and a default font) are defined as variables (in the file EdlDefaults.pm). This allows for simple configuration of a site-specific look and feel, without having to modify 25 widget modules.

These defaults, as well as non-default widget version numbers (major, minor, release) are configurable in the file EdlDefaults.pm. There is no point of changing any of these selected properties in individual widget templates, as the template values are clobbered by the configure() function called from the widget's new() subroutine.

top

Adding Support for New edm Widgets

a) get the widget documentation from edm

set the environment variable EDMGENDOC to 1
start edm and redirect the output to a file, e.g. widgetdoc.dat
interactively create an edl file, which contains the new widget.
save the edl file and exit edm.

widgetdoc.dat would have a section for the new widget, which looks somewhat like this:
.......
# (Static Text)
object activeXTextClass
beginObjectProperties
major <int>
minor <int>
release <int>
x <int>
y <int>
w <int>
h <int>
font <string>
[fontAlign ("left"|"center"|"right")]   /* default = "left" */
fgColor (index <int> | rgb <int> <int> <int>)
[fgAlarm [(0|1)]]   /* present with no value = 1, absent = 0 */
bgColor (index <int> | rgb <int> <int> <int>)
[bgAlarm [(0|1)]]   /* present with no value = 1, absent = 0 */
[useDisplayBg [(0|1)]]   /* present with no value = 1, absent = 0 */
[alarmPv <expandable string>] /* default = "" */
[visPv <expandable string>] /* default = "" */
[visInvert [(0|1)]]   /* present with no value = 1, absent = 0 */
[visMin <string>] /* default = "" */
[visMax <string>] /* default = "" */
[value {
<expandable string> /* line 1 of n */
<expandable string> /* line 2 of n */
      .
      .
}]   /* default = "" */
[autoSize [(0|1)]]   /* present with no value = 1, absent = 0 */
[border [(0|1)]]   /* present with no value = 1, absent = 0 */
[lineWidth <int>]   /* default = 1 */
endObjectProperties
....

b) create a Perl module for the new widget

determine from the widget documentation for the new widget, if the widget contains "list" properties. List properties are those, where the property name is followed by a list of values enclosed in {}. In the example above, the property "value" is a list property.
choose a name for the perl module. Stay with the convention of naming it Edl<widget name>.pm. For the example above, I would choose EdlStaticText.pm
if the widget has at least one list property,

make a copy of EdlStaticText.pm to Edl<widget name>.pm, otherwise
make a copy of EdlRectangle.pm to Edl<widget name>.pm

copy/paste the the self-documenting output from edm into Edl<widget name>.pm.
modify the Edl<widget name>.pm

copy all lines starting with #(<widget>) and including the trailing empty line.
paste these lines into Edl<widget name>.pm replacing the lines bitween the brackets in @edlTemplate
run the ConvertEdlTemplate.pl utility:
ConvertEdlTemplate.pl Edl<widget name>
This utilty inserts the new widget name where required and preformats the edlTemplate.
edit the @edlTemplate list to contain the key/value pairs of the new widget. Replace the self-documenting information with your desired default values. At this point you make decisions on default property values and how to handle optional properties.
In subroutine new(), modify the site-specific configure function as required by the new widget. See site-specific configuration for more details.

c) add support for the new module to the site-specific Perl modules

add a use statement to the file EdlSiteUse.pm
add a widget generation function to the file EdlSiteWidgets.pm, following the template in that file

top

Checking for Consistency

From version 1-11-0p onwards, the distribution contains a consistency check tool checkEdlModules.pl.

The consistency check tool works together with the file widgetdoc.edl and reports

differences between the widget properties of the running edm version and the templates in the Edl....pm modules
differences between the major, minor, release properties of the running edm version and the templates in the Edl....pm modules