Custom wizards are read from the templates/ folder of OMNeT++ projects.
Wizards are implemented by mixing a templating engine (for generating
the output files) and a GUI description language (for custom wizard pages to
gather user input for the file generation). Because of the use of a
templating engine, we will also refer to custom wizards as "content templates."
The IDE offers several OMNeT++ related wizard dialogs: New OMNeT++ Project, New NED File, New Simple Module, and so on. Every content template can contribute to one or more of those wizard dialogs.
In the templates/ folder, every subfolder that contains a template.properties
file is treated as a content template (other folders are ignored). Every
content template folder may contain several types of files:
-
The
template.propertiesfile contains general information about the wizard. It defines the initial value for the template variables and specifies the custom wizard pages to be shown when the wizard is run. -
*.ftlfiles are template files that will be copied (without the.ftlextension) into the target folder after template variable substitution. -
*.xswtfiles describe custom wizard pages that gather user input. -
*.fti(template include) files are included by*.ftlfiles. This can be used to factor out common parts from the template files. The wizard ignores.ftifiles (i.e. does not copy them into the new project or folder). -
*.jarfiles can be used to extend the wizard’s functionality with dynamically loaded Java code. -
All other files are regarded as files that have to be copied into the
target folder verbatim when the wizard runs. The wizard folder may contain
subdirectories which may also contain files of the above type (except
template.properties, of course).
Template processing uses the FreeMarker library (http://freemarker.org) and
all template syntax supported by FreeMarker can be used. In particular, variable
references of the syntax ${varName} will be replaced with the variable value.
The FreeMarker language also offers constructs that make it a full programming language: variable assignments, conditionals, loops, switch statement, functions, macros, expression evaluation, built-in operators, etc., as well as access to fields and methods of classes defined in Java. This means that any algorithm can be expressed in the FreeMarker language, and if that is not enough, one can directly access Java classes using FreeMarker’s Bean Wrapper.
Tip
Documentation for the FreeMarker template language can be found at: http://freemarker.org/docs/index.html
Templates can use several sources for input. They can:
- gather information from the user, using custom wizard pages,
- call any Java code to execute any arbitrarily complex algorithm,
- call external programs, and
- read and write from/to any file on the filesystem
Custom wizard pages are defined in XSWT (http://xswt.sourceforge.net).
XSWT is an XML based language that allows the definition of SWT (the widget set
used by Eclipse) widget hierarchies, without the need to write any code in Java. XSWT also maps
widget properties to XML attributes so the visual appearance of the wizard pages
can be easily tweaked. It is also possible to invoke methods on the generated widgets
and use the SWT layout containers, allowing further customizations. Each .xswt file
in the template directory defines a separate wizard page which can be shown
either conditionally or unconditionally.
Tip
XSWT documentation and a tutorial can be found at: http://www.coconut-palm-software.com/the_new_visual_editor/doku.php?id=xswt:home.
Note
Currently we use XSWT 1.1.2. Newer XSWT versions from http://www.coconut-palm-software.com/~xswt/integration/plugins/ did not work well.