Sample Style Guide used at the PSI

1. FEL-LA85-000-0
Projekt/Project
SwissFEL
Titel/Title Application development style guide for the
SwissFEL
Dokument Nummer/Document Identification
FEL-LA85-000-0
Autor/Author Andreas Lüdeke
Externe Referenz/External reference
Mitautor(en)
Co-Author(s)
Elke Zimoch
Application development style guide for the SwissFEL
Abstract: this guide for the application developers defines rules to ensure
a consistent behaviour of all applications and a common integration of
high level applications into the EPICS control system. It should ease the
task of the application developer and simplify the usage of the
applications for the accelerator operators.
Organi
sation
Verteilername
Name of distribution
Adresse
Address
Anzahl Kopien
Number of copies
Überprüft durch (Name):
Approved by (name):
Datum / Unterschrift
Date / Signature
Dokument Status
Status of document
Anzahl Seiten
Number of pages
7
Datum
Date
25.08.2009
FileS
erver
File
Nam
e
Unterschrift Autor
Signature of autor
PAUL SCHERRER INSTITUT Page 1

2. FEL-LA85-000-0
Version Updates
Revision Datum
Date
Autor
Author
Änderung
Modification
0 2-Jun-2009 Andreas Lüdeke Creation
Table of content
1 INTRODUCTION 3
2 BASIC APPLICATION REQUIREMENTS.......................................................................................3
2.1 Basic user interface layout.............................................................................................................3
2.1.1 General Displays 3
2.1.2 Main window title 3
2.1.3 Menu bar 3
2.2 Usage of fonts 4
2.3 Usage of colors 4
2.3.1 Reserved colors 4
2.3.2 Standard colors 4
2.4 Standard Labels 5
2.5 Standard widgets 5
2.6 Application start-up 5
2.7 Example panels 5
2.7.1 MEDM subsystem examples......................................................................................................6
2.7.2 MEDM subsystem templates......................................................................................................6
3 APPLICATION DATA EXPORT.......................................................................................................7
3.1 Export of calculated scalar data.....................................................................................................7
3.2 Export of calculated data to files....................................................................................................7
PAUL SCHERRER INSTITUT Page 2

3. 1 INTRODUCTION
The learning curve for the proper usage of an application can be accelerated if different
applications follow the same user interface design rules. This document will define the basic design
rules for user interfaces of application used in the context of the SwissFEL project. In addition it
provides a basic guideline for the integration of high level applications into the EPICS control
system. It should therefore ease the task of the application developer and simplify the usage of
those applications for the accelerator operators.
The document is kept as brief as possible. In case of doubt, look at the MEDM example screens.
This is supposed to be a “living document”. The standards should be extended whenever a
consensus is found about additional guidelines. Please send your suggestions to the author.
2 BASIC APPLICATION REQUIREMENTS
We will distinguish two classes of applications: “expert applications” with the scope to be used by a
small number of people and “operation applications” that will eventually be used by a larger
number of different people. The specifications below should be used as a guideline for the creation
of user interfaces of expert applications. They should be considered as mandatory for all operation
applications.
2.1 Basic user interface layout
2.1.1 General Displays
Whenever feasible the user interface should be made as MEDM display. This ensures a de-
coupling of the display and the actual functionality of an application.
All MEDM displays should have a title line (see examples section 2.7). The height of the title-text
should be exactly 20 pixel. At the right end of the title line should be a “Help” menu button with a
height of 27 pixel (provides the same font than the title). For the content of the help menu see
section “Menu bar” below. There can be additional menus left of the “Help” menu, e.g. for related
panels (next section of the same subsystem, other subsystems for the same section, ...) or other
related functionality (save & restore, archive viewer, ...).
2.1.2 Main window title
The main window of each application should have a title that matches the entry name in the
launcher (See http://www.sls.psi.ch/controls/help/howto/launcher.html) to start that application.
For MEDM panels the program G_CS_medm allows to set a title of an MEDM window at startup.
2.1.3 Menu bar
For non-MEDM applications the main window should have menu bar, if feasible. Two menus are
mandatory: the leftmost menu named “File”, containing at minimum “Exit” as a last entry to exit the
application. The rightmost menu is called “Help” and must contain at least two entries: at least on
“Manual” entry and an “About” as the last entry. The later should open a window to tell the CVS
version and author of the application. From MEDM you can just call the script “G_CS_about” with
the argument string “&T $Header: $- &” to accomplish that. The “Manual” entry should open a Wiki
page with the default browser. Use the command “htmlview” to start the browser. The Wiki entry
should provide a general description of the application. At minimum the Wiki entry should contain
one sentence about the purpose of the display.

4. 2.2 Usage of fonts
Text fonts should have 20 pixel height, if feasible. Smaller fonts should be avoided. Do not use
many different types of fonts in one panel. Sans-serif fonts should be preferred for readability.
2.3 Usage of colors
Since MEDM screens will be used for most
subsystems, they define the color standard that should
be followed in all other applications. Use color with
care, only if you need them. MEDM has a fixed color
palette (see Fig. 1). The colors named like “MEDM <n>”
in section 2.3.2 do refer to the color labeled <n> in Fig.
2.1.
2.3.1 Reserved colors
Three colors are reserved, do not use any of them for static text or graphics, only for conditional
text and graphics:
• white (#FFFFFF) signifies invalid states, like connection loss, division-by-zero, etc.
• red (#FF0000 and all colors close to it) is reserved to signify alarm states. It must
always show a condition bad for the current task, for the subsystem or the beam.
• yellow (#FBFB04) signifies a warning state, or being close to a bad condition.
• green (#00CD00) signifies good states, everything is fine.
2.3.2 Standard colors
Table 1: Standard foreground colors
Foreground color MEDM RGB hex. RGB decimal
Normal text (for good readability): black MEDM 14 #000000 0,0,0
• Curve graphs for horizontal properties MEDM 53 #2A63E4 42,99,228
• Curve graphs for vertical properties MEDM 38 #8B1A96 139,26,150
• Curve graphs for longitudinal properties MEDM 34 #CD6100 205,97,0
Table 2: Standard background colors
Background color MEDM RGB hex. RGB decimal
normal title background color MEDM 0 #FFFFFF 255,255,255
Title background color for simulation (no machine access) MEDM 38 #8B1A96 139,26,150
Main background color (for good contrast) MEDM 2 #ECECEC 236,236,236
Text that changes between the reserved colors MEDM 3 #DADADA 218,218,218
Controller of PV influences the beam directly or indirectly MEDM 56 #D4DB9D 212,219,157
Controller of PV has no influence on the beam MEDM 50 #99FFFF 153,255,255
Buttons to open a new window directly MEDM 46 #B79D5C 183,157,92
Menu buttons to open a pull down menu MEDM 40 #8088FF 128,136,255
Buttons to execute scripts that write to PVs are colored like control widgets writing to a PV.
Figure 1: MEDM color palette

5. 2.4 Standard Labels
Labels of buttons should have standardized text to avoid confusion:
• “Close”: closes current window, all other windows of the same application remain open.
• “Exit”: closes all windows of the current application and ends the application.
• “Abort”: to cancel an active process that had been started by the application. E.g. halt
motors, stop magnet current modifications, etc. The button should be visible but disabled
while process is inactive.
• “Pause”: to pause an active process that had been started by the application. Use this
term only if the process can be continued afterwards.
• “Print”: send data to the printer.
• “Publish”: send data to the log-book.
• Append “..” at the end of a label if a new window will be opened. This applies to buttons to
open a window (MEDM 46 Background color) and to the entries in a menu button, if they
open a new window. Exception: entries in the “Help” menu don't need to append two dots.
The text of the button can be extended to signify the process or the type of data, e.g. “Stop
Measurement” or “Print Configuration..”. But the label should always start with the standard text.
2.5 Standard widgets
MEDM provides a “composite” feature that allows to include an ADL file within any panel. Macro
variables can be passed to the included file. This allows to simplify the creation of MEDM panels
and takes care that e.g. a valve is displayed exactly the same in all panels.
A set of composites will be provided for MEDM. All MEDM panels must use those composites
whenever feasible. Some composites will be generic, e.g. a widget to display a formatted value
next to it's unit with alarm colors. If you need one that does not exist, please report to the author of
this document. Some composites are related to a subsystem, e.g. the display of the state of an
valve. If one is missing here, the controls responsible for this subsystem should be contacted.
All non-MEDM applications should use widgets in accordance with the MEDM composites.
2.6 Application start-up
Applications should start up within less than a second, to provide immediate response to the
operator. Otherwise a startup screen must be displayed, telling the estimated time until the
application will be ready.
Generic applications should allow a preconfigured startup. E.g. a camera readout application that
allows different functions to be fitted to the picture should allow start-up options to select a specific
camera and perform a specific fit. This will allow to call the same application several times from the
launcher, to perform different specific measurements, e.g. “Measure beam profile at XXX”.
2.7 Example panels
The following MEDM examples should illustrate the basic user interface requirements. The file
names of those examples are provided with each screen-shot to allow the application programmer
to use those example screens as templates for new panels. We will provide two types of examples:
subsystem templates and subsystem examples. The templates will contain all available
composites for the given subsystem. The MEDM panel is not meant to be used for anything, just
as a canvas to copy composites from. The subsystem examples on the other hand should serve as
full scale examples for real panels. They do access a simulation database that runs on
softioc.psi.ch. To access the related channels you should type the command “cao” in a terminal in
the PSI office network before starting the MEDM panel.

6. 2.7.1 MEDM subsystem examples
This version will contain only one subsystem examples for magnets. The example should give an
impression of the general layout of a standard MEDM panel (see Fig. 7 at the end of the section.)
2.7.2 MEDM subsystem templates
Each subsystem controls contact should provide one or more template screens that contain
composite examples for all available devices. We will present a first draft of those templates for the
subsystems magnets and vacuum. The name of such a template should always be according to
the subsystem project: <prefix>_template[-<n>].adl
The prefix is given by the CVS project. The MEDM panel F_CS_master_template.adl contain
buttons to launch the related displays of all subsystems <X> (“F_<X>_template.adl”) and those
panels should be linked to the existing sub project <Y> templates F_<X>_<Y>_template.adl by a
related panel button. Another button allows to edit the same template files.
Figure 3: F_CS_template.adl
Figure 4: F_MA_template.adl
Figure 5: F_CS_template_2.adlFigure 6: F_VCS_template.adl
Figure 2
: F_CS_master_template.adl

7. The channels accessed from those example composites should not be connected to any hardware.
Provide soft channels on softioc.psi.ch to be accessed by the tempate panels. (Currently those
template panels do access real OBLA 4MeV devices. Use “caobla” before starting those panels.)
3 APPLICATION DATA EXPORT
3.1 Export of calculated scalar data
If an application calculates relevant data for the operation of the accelerator, this data should be
written to EPICS channels directly whenever calculated. That will allow to use the EPICS standard
applications for those values: archiving, alarming, strip-charts, correlation plots, etc.
The channels for this data export should follow a common template: if the value has not been
written for a given time period, the EPICS database should raise an alarm. This allows to signal a
failure of the application to the operator. At startup the application can determine by the very same
alarm channel if another instance of the application is already writing to the specific channel.
A generic application should export data relevant to operation to different channels depending on
the type of measurement. E.g. a camera application should export the measured beam dimensions
to different EPICS channels depending on the selected camera and the fit method. A generic
channel may be used for many different scalar values of one application when those values have
no specific relevance for operation. This allows to use strip-charts or correlation plots for those
values.
3.2 Export of calculated data to files
Applications may generate non-scalar data that should be saved for post processing. The data
should be saved in the Nexus file format (See https://wiki.intranet.psi.ch/XFEL/NexusHDF5 or
http://www.nexusformat.org), wherever applicable. All files should be saved in an application
dependent sub-directory of $SETUPBASE.
Figure 7: Example magnet panel F_MA_mag-example.adl