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)
Version 1.2 production version
Rolf Keitel 2011/02/03 renamed modules to fit perl directory convention.
needs changes to existing scripts (see example code)
widget templates still edm-1-11-0p

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
Widget Generator Functions
Technical Details
Download and Installation
Site-Specific Configuration
Adding Support for New edm Widgets
Checking for Consistency
Python Version
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;

use Edl::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::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();



Note:
The finish function may take a file name as parameter. This overrides the file name given in the Edl constructor.
If this parameter has the value "stdout", the edl file content is written to standard output, i.e. the generating script may be
used as a filter to edm to generate displays "on the fly" (see the edm manual about filters).

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
Head.pm module to generate the edl file header
Defaults.pm module for site-specific configuration
<widget>.pm one Perl module <widget>.pm 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

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 Defaults.pm

top



Download and Installation

NOTE: By downloading part or all of this software package, you agree to the Terms of the EdlBuild Licence agreement.

Contents of tar file:

a)  EdlBuild related files  (supported by R.Keitel )
Edl.pm
main module
<widget>.pm complete set of  widget modules
Cp.pm, Panels.pm, Panels2.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:
  1. Download the tar-ball and the example script from here
  2. Extract the perl modules with the tar -xvf command to <wherever you like>
  3. 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

  1. set the environment variable EDMGENDOC to 1
  2. start edm and redirect the output to a file, e.g. widgetdoc.dat
  3.  interactively create an edl file, which contains the new widget.
  4. 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

  1. 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.
  2. choose a name for the perl module. Stay with the convention of naming it <widget name>.pm.  For the example above, I would choose StaticText.pm
  3. if the widget has at least one list property,
  4. copy/paste the the self-documenting output from edm into <widget name>.pm.
  5. modify the <widget name>.pm

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

  1. add a use statement to the file EdlSiteUse.pm
  2. add a widget generation function to the file SiteWidgets.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
widgetdoc.edl contains one instance of each edm widget.

Follow these steps:
  1. set the environment variable EDMGENDOC:
    setenv EDMGENDOC 1
  2. start edm:
    edm widgetdoc.edl >& widgetdoc.dat
  3. from within edm, save the .edl file. This writes the widgetdoc.dat file
  4. run the consistency check tool:
    checkEdlModules.pl widgetdoc >& xxx.dat


top


Python Version

A Python version of the EdlBuild library is now available in the download area. Note that this library has undergone much less testing than the Perl version. If you find any problems, please provide feed back to the author.



Limitations and Known Problems

Nothing known at the moment.

Report any problems to R.Keitel

top