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
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();
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
- 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 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:
- Download the tar-ball and the example script from here
- Extract the perl modules with the tar -xvf command to <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 <widget name>.pm. For the example
above, I
would choose StaticText.pm
- if the widget has at least one list property,
- make a copy of StaticText.pm to
<widget name>.pm, otherwise
- make a copy of Rectangle.pm to <widget
name>.pm
- copy/paste the the self-documenting output from edm into
<widget name>.pm.
- modify the <widget name>.pm
- copy all lines starting with #(<widget>)
and including the trailing empty line from widget.dat.
- paste these lines into <widget name>.pm
replacing the lines bitween the brackets in @edlTemplate
- run the ConvertEdlTemplate.pl utility:
ConvertEdlTemplate.pl
<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
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
- 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
widgetdoc.edl contains one instance of each edm widget.
Follow these steps:
- set the environment variable EDMGENDOC:
setenv EDMGENDOC
1
- start edm:
edm
widgetdoc.edl >& widgetdoc.dat
- from within edm, save the .edl file. This writes the
widgetdoc.dat file
- run the consistency check tool:
checkEdlModules.pl widgetdoc >& xxx.dat
top
Limitations
and Known Problems
Nothing known at the moment.
Report any problems to
R.Keitel
top
