This is a short introduction to the MeVisLab Definition Language (MDL), in which all *.def, *.script and various other files for the MeVisLab are written. The MDL is a configuration and layouting language, not a real programming language. You can set tags and values for the tags, but there are some extensions to this static scheme.

If found in *.def or *.script files, the MDL is used for layouting the GUI of modules. That is the arranging of fields implemented in C++ on a module panel or adding new fields and functionality to modules, especially to macro modules.

Besides just layouting of fields for a module, the MDL offers also certain hubs for various fields to call scripting methods (Python or JavaScript) on occasions like altering a field's value or opening a module's panel. Most MDL controls can be scripted from Python and JavaScript, a scripting link into the MeVisLab Scripting Reference is given where appropriate.

MDL is tag-based. Typically, a tag is set to a certain value or to a group of tags. There are also special tags to conditionally parse parts of a file or to test for miscellaneous conditions.

1.1.1. Tags and Values

Setting a tag is simple:

TAGNAME = VALUE

The equal-sign ("=") has to be used between every tag and its value, except for groups, where it is optional (see "Groups"). TAGNAME as well as VALUE need to be a single token. If a token should contain whitespace, there are various ways to quote this value.

The most simple method is to enclose a value containing whitespace in parentheses:

myTag = "Example with whitespace and \"parentheses\" and a \\ backslash "

As you can see, parentheses and backslashes are escaped with backslashes, which can be annoying when you need to use many of them. There are two alternative ways to enclose long values that contain special characters:

// enclosing with "* *"
      
myScript1 = "*js:                 
   function shakespeare () {
     debug("2b | !(2b) => ?");
   };
*"


// enclosing with @@

myScript2 = @@js:                 
   function escaped () {
     debug("*catch @ falling star*");
   };
@@

Inside strings starting with a parenthesis-star and ending with a star-parenthesis or inside of strings enclosed in double-@ (at) you can use all characters without escaping them except for the backslash char. Only if you want to use a sequence of characters that is the same as the ending of the used delimiters, you need to escape them with backslashes.

If you use any kind of quoting, you need to escape backslashes with a double backslash (\\).

Overview of quoting and the characters you need to escape with a backslash:

" ... "

escape " with \" or use ' in Python or JavaScript instead

escape \ with \\

"* ... *"

escape *" with *\"

escape \ with \\

@@ ... @@

escape @@ with @\@

escape \ with \\

1.1.2. Tag Data Types

The different tags in the MDL have different data types. Those data types are listed here with a general explanation. A more detailed explanation can be found at the actual tags.

STRING

An arbitrary description string. If the string contains spaces, it has to be enclosed in quotes.

The tag data of type STRING may be translated to other languages by an internationalization mechanism.

This type is used as a control's name, as its title, comment, whatsThis- and toolTip text.

Examples:

title   = SomeExampleTitle
comment = "This example comment contains spaces"

STRINGLIST

A list of strings, separated by commas. Since the single string entries are not allowed to contain spaces, the string list does not need to be enclosed in quotes.

The tag data of type STRINGLIST may be translated to other languages by an internationalization mechanism.

This type is used for the genre and group tags.

Examples:

genre = Lung
group = Release, LungPrivate

NAME

A unique identifier which must not contain spaces.

This type is used for identifying objects across script, scripting and C++ code. Tags such as item, module, DLL, field panel or deprecatedName are of this type.

NAMELIST

A list of unique identifiers, separated by commas. The unique identifiers must not contain spaces.

This type is used for the filter tag of the EventFilter.

To get a list of the possible values of the filter tag, use the auto-completion of the texteditor MATE.

BOOL

A Boolean value.

Possible values are Yes, No, True, False, On and Off.

UINT

An unsigned integer value.

INT

An integer value.

FLOAT

A floating point value.

FIELD_OR_FLOAT

Either a unique identifier of an existing number field or a floating point number.

This type is used for a field's min and max tags.

Example:

Interface {
  Outputs {}
  Inputs  {}
  Parameters {
  
    Field maxValueField {
      type  = Float
      value = 0
    }
  
    Field controlledField {
      type  = Float
      value = 0      
  }
}

Description {

  Field controlledField {
    min = 0
    max = maxValueField
  }
}

ENUM

One of a fixed list of unique identifiers.

Have a look at the detailed description of tags of type ENUM for the possible values and the default value. Also, the possible values are shown in MATE's auto-completion.

FIELD

A unique and existing identifier of a field.

This type is used i.e., for the field tag of the Accel.

FIELDLLIST

A list of unique and existing field identifiers, separated by commas.

This type is used for the list of fields in the Persistence description.

FIELDLEXPRESSION

A Boolean expression that is based on field values.

This type is used for the tags dependsOn and visibleOn. Have a look at the examples of those tags for a more detailed explanation.

PATH

A relative or absolute path to a directory. If it is a relative path, useful variables are listed in Section 1.1.4, “Variables”.

The path delimiter is a "/", independent of the platform.

FILE

Same as PATH but with a specified file. This file can be i.e., a scripting file (.py), an HTML file (.html) or a network file (.mlab).

SCRIPT

A unique name of a scripting function implemented in a separated and included scripting file or a single line of scripting.

COLOR

A color definition, explained in more detail here.

KEYSEQUENCE

A keysequence or shortcut to trigger certain functionality. The set string may be translated to other languages by an internationalization mechanism.

A KEYSEQUENCE is used in menus and in the Accel.

RICHTEXT

A string containing HTML formatting.

This type is used in the TextView or similar controls.

A table with all supported HTML tags can be found in the chapter RichText.

FORMATSTRING

A C-like expression for formatting a (floating point) number.

Have a look at the NumberEdit control for more information.

REGEXP

A regular expression for string matching.

This type is used in the LineEdit control for validating the entered string.

QTSLOT

A Qt-slot which is triggered if a control emits a signal.

This type is used in the MenuItem.

1.1.3. Groups

Group tags are used for hierarchical tags. This means that you can build not only flat tag lists but also complete tree hierarchies. A group tag starts with a tag name, an optional value and an opening curly-brace, it ends with a closing curly-brace. Inside of the braces you can set normal tags with values or other group tags:

myGroup exampleGroup {
    normalTag = "This is a normal tag"
    groupInside {
        insideTag = "Another example tag"
    }
}
tagOnlyGroup {
    normalTag = "This group has no value"
}

Contrary to normal tags, a group tag does not need to have a value. The second example above shows a group that has only the tag name but no value, before the group is opened.

1.1.4. Variables

MDL has some predefined variables that are useful for its purposes. To get the value of a variable, write its name inside a pair of parentheses with a dollar sign prefix: $(VARNAME).

The following variables are defined:

LOCAL - Contains the full path of the currently parsed file.

HOME - Home directory of the user.

PackageIdentifier - Unique name, the structure is: "MLAB_PackageGroup_PackageName"

In addition to these predefined variables, you can get the values of all tags from the mevislab.prefs file.

Variables in MDL can be escaped by writing $(*VARNAME*), which expands to $(VARNAME).

1.1.5. Including Files

MDL allows you to include files with the #include statement. This is equivalent to pasting the given file at the position of the include statement:

#include $(LOCAL)/anotherfile.script

The same file can be included multiple times at different places in an MDL file. It is recommended to name included files either *.script or *.inc. You should not use the *.def extension, because this is reserved for module definition files and would be read automatically by MeVisLab on startup.

1.1.6. Conditions and Special Statements

MDL allows to parse or skip parts of files depending on conditions. Additionally there are some statements that allow simple debugging and printing of messages.

#ifset and #ifnset are used to test if a variable is set to one of the following values: true, on, yes, 1 . If the variable is not set or has a different value, the block is not parsed.

The variables can be defined in the mevislab.prefs file.

#ifset ApplicationAdvanced {
   // if $(ApplicationAdvanced) is defined and set to true, on, yes or 1, parse inside this block
   Field advancedField {}
}
#ifnset ApplicationAdvanced {
   // if $(ApplicationAdvanced) is undefined or not set to true, parse the following block
   Field normalField {}
}

#ifdef and #ifndef are used to test for existence of variables (and not its value)

#ifdef CPU {
    // if $(CPU) is defined, parse inside this block
    cpuTag = "$(CPU)"
}
#ifndef CPU {
    // if $(CPU) is undefined, parse the following block
    cpuTag = "CPU unknown"
}

The #if statement is another conditional for parsing blocks. With #if you can test the boolean value of a variable or compare two variables as strings or numbers or compare a variable with a static string. The following operations are possible for compare: <, >, ==, >=, <=, !=

#if $(DEBUG) {
    // Parse this if DEBUG is a variable and has the boolean value true
    debugTag = "Debugging is fun"
}
#if "$(VERSION) >= $(MINVERSION)" {
    // If the variables can be parsed as floating point numbers, make numeric comparison
    // otherwise a lexical comparison is done
    featureForVersion = true
}
#if "$(HOME) == $(LOCAL)" {
    // Parse this if the current MDL file resides in the user's home directory
    myHome = "is my castle"
}

The #echo statement allows you to print out the value of variables or any other string to the console, which can be very useful for debugging:

#if $(DEBUG) {
    #echo "HOME-Dir is $(HOME)"
}

The #abort statement is used to print an error message and to stop the parser:

#ifndef DefaultFont {
    #abort "No default font available!"
}

1.1.7. Comments

Comments in MDL are the same as in C++:

// This is a comment before a tag
myTag = myValue
/*
 The following tags are not parsed, because they are inside a comment block
 tag01 = unparsed
 tag02 = unparsed
*/
anotherTag = anotherValue  // Comment after Tag/Value Pair

Comments can be placed anywhere in the MDL file, but not between a tag and its value.

1.1.8. Naming Conventions and Limitations

Although it is not needed by the parser, it is recommended to use tag names without whitespace and to separate words in tag names with uppercase characters. Both of the following examples are allowed, but the latter is recommended:

"Tag with four words" = "The Value"
tagWithFourWords = "The Value"

You can use any character sequence for tag names as long as they are parsable as one tag. To start tag names with characters that end or start new syntactic constructs, for example "{" or "=", you have to enclose them in parentheses or use the same methods as for values.

1.1.9. Validation

MeVisLab contains a complete definition of allowed MDL tags and throws warnings if the validation of an MDL script fails. Usually it adds a link to the online documentation so that you can see what tags are possible in the scope you are in.

1.2. Module Declaration

1.2.1. Module (Abstract)

MeVisLab supports three different types of modules, which are derived from an abstract module:

MLModule (an image processing module using the ML)
InventorModule (a visualization module derived from OpenInventor)
MacroModule (a macro module that encapsulates a internal network and has its own panel/script)

The following module tags are supported by all module types. Details on the different modules are given in the following sections.

Dynamic scripting: MLABModule

[MLModule|InventorModule|MacroModule] NAME {
      
  genre              = STRINGLIST
  author             = STRINGLIST
  status             = STRING
  group              = STRINGLIST
  comment            = STRING
  keywords           = STRING
  exampleNetwork     = FILE
  seeAlso            = STRING
  documentation      = FILE
  
  scriptVersion      = FLOAT
  deprecatedName     = STRING
  hideModule         = BOOL
  backgroundImage    = FILE
  externalDefinition = FILE
  
  Interface {
    Inputs {
      Field NAME {...}
      ...
    }
    
    Outputs {
      Field NAME {...}
      ...
    }
    
    Parameters {
      Field NAME {...}
      ...
    }
  }
  
  Description {
    Field NAME {...}
    ...
  }
  
  Commands {
  
    source = FILE
    
    // more source tags...
    
    
    initCommand        = SCRIPT
    wakeupCommand      = SCRIPT
    droppedFileCommand = SCRIPT
    
    FieldListener [FIELD] { ... }
  }
  
  Deployment {
  
    directory = PATH
    ...
    module   = NAME
    ...
    DLL      = NAME
    ...
  }
    
  Persistence {
  
    fields = FIELDLIST
  
    Module NAME {
      fields = FIELDLIST
    }
  }
  
  
  Window [NAME] {
    ...
  }
  
  // more windows...
  
}

genre = GENRENAMES

specifies one or more genre this module is in. Genres are separated by "," and have to be declared in the global genre file of MeVisLab. If a given genre is not defined, you will get a validator warning and the module is put into the "Other" genre. The genre tag is used to generate automatic entries in the Modules menu of MeVisLab and in the documentation. A module can be in multiple genres.

Example: genre = "Image, Diffusion"

author = STRINGLIST

gives the author(s) of the module, starting with the primary author. Authors have to be separated by "," and should contain first and last name.

Example: author = "Florian Link, Bernd Kuemmerlen"

	Warning
	Do not write anything except the authors' names in this tag, because the names are used for automatic documentation generation.

status = STRING

gives the status of the module.

Currently used words are:

Stable
Work-in-progress
Test
Deprecated

group = STRINGLIST

this is a list of group names separated by ",". If no group is given, the module is always visible in MeVisLab. If a list of groups is given, the module is only visible in MeVisLab if one of the groups is enabled in the MeVisLab prefs file (mevislab.prefs) via the "EnabledGroups" tag.

	Note
	Visible means that the user can find the module in the search dialogs and in the Modules menu. The modules can still be loaded from a saved network or inside an application, even if they are not visible.

Special groups:

- Release : if the string contains the keyword "release", the module is visible in the MeVisLab release version (otherwise it is not visible in the release, regardless of the other groups!)

- Deprecated : if the string contains the keyword "deprecated", you have to enable the "deprecated" tag to see the modules, regardless of the other groups

Examples:

group = Deprecated // module will only be visible if "EnabledGroups" contains "deprecated"

group = Release // module will be visible in MeVisLab release

group = LungPrivate // module will only be visible if "EnabledGroups" contains "LungPrivate" and if MeVisLab is not in release mode

group = Release, LungPrivate // module will only be visible if "EnabledGroups" contains "LungPrivate"

comment = STRING

a short comment, which is shown in the MeVisLab help system and on the network.

(We recommend that you only write a short comment here and use the documentation tag for further documentation.)

documentation = FILE

a file that gives HTML documentation for this module.

If the documentation tag is not given, it is automatically assumed to be at

$(LOCAL)/html/ModuleName.html

You should only use the documentation tag if you are referencing a HTML file that does not follow the convention above (e.g., one HTML file that documents several modules).

keywords = STRING

keywords that are used in the MeVisLab search to find a module by its keywords. The keywords are separated by " ".

Make sure that you only use adequate keywords, otherwise your module will be found more often than wanted. Having no keywords decreases the possibility that someone finds the module.

exampleNetwork = FILE

gives an example MeVisLab network that the user can open to see how the module could be used in connection with other module.

seeAlso = STRING

reference to other modules that are related to this module, separated by " ".

Example: seeAlso = "SoView2D SoOrthoView2D"

externalDefinition = FILE

this allows to define the module's windows etc. in an external file, typically with the file extension ".script". It is advised to use the naming convention $(LOCAL)/ModuleName.script if you use this tag. The advantage of using this feature is that the MDL file needs only be parsed when the module is really created and not when MeVisLab is started. Make sure that you still provide the simple tags (author, comment, etc.) in the *.def file so that they are available when MeVisLab is started.

Example: externalDefinition = $(LOCAL)/ModuleName.script

	Tip
	This is typically used in MacroModules, especially when they are applications, to avoid that MeVisLab reads the whole application definition on startup.

backgroundImage = FILE

specifies a background image that is used on the box drawn in the MeVisLab network (instead of the default image).

deprecatedName = STRING

defines an old (deprecated) name for this module, so that networks that contain a module with this name can still be loaded even if the module name was changed.

hideModule = BOOL (default: No)

hides the module, which effectively means that it can neither be found nor created in MeVisLab. This can be used for debugging purposes to turn modules on/off.

1.2.1.1. Interface

The interface section is used to declare any extra fields of a module. While it is possible to use the interface section in a ML/InventorModule, it is typically only used for MacroModule, since the ML and Inventor modules get their fields automatically from C++. If you want to add a description for a C++ field, refer to the Description section.

The interface section can contain three subgroups: Inputs, Outputs and Parameters. Inputs and Outputs are typically Image, SoNode or MLBase fields, while the Parameters section typically holds parameter fields like floats, vectors, colors etc. The declared fields can be both standalone script fields or they can alias an internal field of the internal network of a MacroModule.

// script field:
Field NAME {
  type         = ENUM
  value        = STRING
  comment      = STRING
  hidden       = BOOL
  priority     = INT
  persistent   = BOOL
  min          = FIELD_OR_FLOAT
  max          = FIELD_OR_FLOAT
  internalName = FIELD
  legacyValue  = STRING
  removed      = BOOL
  
  // for enums:
  items {
    item NAME {
      title          = STRING
      deprecatedName = STRING
      
      // more deprecatedName tags
    }
    ...
  }
  // old deprecated enum syntax:
  values = STRING
}

type = ENUM

defines the type of the field (is automatically given if internalName is used).

Possible values:

String
Int, Integer
Float
Double
Bool
Trigger
Vec2f, Vector2f, Vec3f, Vector3f, Vec4f, Vector4f
Plane
Rotation
Color
Matrix
Enum
Sonode
Image
Mlbase

value = STRING

given default value for the field (will only be assigned when a module is newly created, NOT on reload of a module), will be overwritten by a stored value when loaded from a network.

legacyValue = STRING

given default value for the field when a module is loaded from a network and no value was specified for the field in the saved network. This allows to give a new default value with the value tag and to keep old networks working by setting a compatible legacyValue for old networks.

comment = STRING

a comment describing the field (which is shown at the input/output tool tip).

hidden = BOOL (default: No)

set if the field should be visible in the MeVisLab network (this can be used to hide existing input/output images).

priority = INT (default: 100)

set the priority of the field. A value of 0 means that the field has high priority and GUI controls depending on this field will be updated immediately when the field changes.

persistent = BOOL (default: Yes)

set if field value should be stored in networks (save to disk and copy+paste).

min = FIELD_OR_FLOAT

gives a minimum value for the field, only works on Number fields. The value can be given as a float value or as the name of another field which provides and updates the minimum value if the min field changes.

max = FIELD_OR_FLOAT

gives a maximum value for the field. It only works on Number fields. The value can be given as a float value or as the name of another field which provides and updates the maximum value if the max field changes.

removed = BOOL (default: No)

declares this field as removed (should only appear in the Description section) and avoids warnings when a network is loaded which contains stored values for the field.

internalName = FIELD

defines that the field should alias an internal field of the internal macro module network.

If the internal name is given, the type of the generated field cannot be selected and is given by the internal field.

deprecatedName = NAME

gives an old name to the field, which allows to rename fields in MacroModules/C++ and keep old networks and scripts working. When the deprecatedName appears anywhere in a GUI description, a stored network or in scripting, it is automatically mapped to the name of this field.

(Any number of deprecatedName tags can be given and are all parsed.)

items

if the type of the field is enum, you can specify the enumeration items with this tag.

item = NAME

specify the (token) name of the item

title = STRING

specify the user visible name of the item

deprecatedName = STRING

specify an old deprecated name for the item, which can be used on setStringValue and which causes the enum to take the value of item instead of the old value

This tag is used to allow old networks and scripts to work, even when enum items have changed or have gone away completely.

values = STRING

defines the enum values in a comma-separated list, this tag is deprecated and should no longer be used, use items instead.

1.2.1.2. Description

The description can be used instead of the Interface section to assign extra properties to existing C++ fields. You cannot create new fields in the description section, only add things that are not given in C++.

Description {
  Field NAME {
    value          = STRING
    legacyValue    = STRING
    comment        = STRING
    hidden         = BOOL
    priority       = INT
    persistent     = BOOL
    min            = FIELD_OR_FLOAT
    max            = FIELD_OR_FLOAT
    deprecatedName = NAME
    
    // for enums:
    items {
      item NAME { 
        title = STRING 
      }
      deprecatedName = STRING
      
      // more deprecatedName tags
      ...
    }
   ...
  }
}

value = STRING

given default value for the field (will only be assigned when module is newly created, NOT on reload of a module), will be overwritten by a stored value when loaded from a network.

legacyValue = STRING

given default value for the field when a module is loaded from a network and no value was specified for the field in the saved network. This allows to give a new default value with the value tag and to keep old networks from working by setting a compatible legacyValue for old networks.

comment = STRING

a comment describing the field (which is shown at the input/output tool tip).

hidden = BOOL (default: No)

set if the field should be visible in the MeVisLab network (this can be used to hide existing input/output images).

priority = INT (default: 100)

set the priority of the field, a value of 0 means that the field has high priority and GUI controls depending on this field will be updated immediately when the field changes.

persistent = BOOL (default: Yes)

set if field value should be stored in networks (save to disk and copy+paste).

min = FIELD_OR_FLOAT

gives a minimum value for the field. It only works on Number fields. The value can be given as a float value or as the name of another field which provides and updates the minimum value if the min field changes.

max = FIELD_OR_FLOAT

deprecatedName = NAME

(any number of deprecatedName tags can be given and are all parsed)

items

if the type of the field is enum, you can specify the enumeration items with this tag.

item = NAME

specify the (token) name of the item

title = STRING

specify the user visible name of the item

deprecatedName = STRING

specify an old deprecated name for the item, which can be used on setStringValue and which causes the enum to take the value of item instead of the old value

This tag is used to allow old networks and scripts to work, even when enum items have changed or have gone away completely.

1.2.1.3. Commands

The commands section is used to add script files and commands to the module.

The general sequence for a module initialization is:

Initialization of Modules fields
Script call to initCommand
Creation of FieldListeners
Restoration of outside field connections to other modules in a loaded network
Script call to wakeupCommand

The detailed order is:

Creation of the internal C++ ML/Inventor class or loading the internal MeVisLab network of the MacroModule
Reading internal fields from C++
Creation of self/instanceName fields
Creation of Interface fields (given in the Interface section) and parsing of tags in the Interface and Description section (except for min/max values)
Restore of persistent stored fields (via setStringValue)
Loading of Python or JavaScript given in Commands source tags
Creation of min/max values (from the Interface and Description section)
Script call to initCommand
Creation of FieldListeners given in the Commands section
Field connections to other modules in a network that is restored (from disk or paste buffer) are done
Script call to wakeupCommand

Commands {
  source             = FILE
  
  // more source files...
  
  
  initCommand        = SCRIPT
  wakeupCommand      = SCRIPT
  finalizeCommand    = SCRIPT
  droppedFileCommand = SCRIPT
  
  FieldListener [FIELD] { ... }
  ...
}

source = FILE

give a script file to be loaded in the script context of this module. Python or JavaScript variables, classes and functions declared in the file are available in all script calls to this module. This tag can be used for multiple files, the files are parsed in the order of declaration

The file extension .py specifies Python script files.

The file extension .js specifies JavaScript script files.

Example: source = $(LOCAL)/ModuleName.py

initCommand = SCRIPT

script command that is called when the module is created on a network. At the time of this call, the field connections to other modules in the network have not yet been established.

wakeupCommand = SCRIPT

script command that is called after the module is created on a network and all other modules have been also created and after all field connections have been established.

finalizeCommand = SCRIPT

script command that is called when the module's script context is deleted. It can be used to cleanup resources that need to be removed or cleared.

This command is called when a module is reloaded or when it is finally deleted, which may occur later than expected because of the undo/redo buffer.

(Typically all Python and JavaScript resources are cleaned automatically, so you will probably never need this command.)

droppedFileCommand = SCRIPT

script command that is called when the user drops a file on the module's box on the network (e.g., used in ImageLoad to accept dropped filenames).

FieldListener [FIELD]

the commands section can contain multiple FieldListeners, see FieldListener for detail on what a FieldListener can be used for. The listeners declared in the commands section are active after the module has been created until the module is deleted. This is typically used to provide functionality to a MacroModule's fields and react on field changes which are independent of the user interface. If you want to have a FieldListener that changes the user interface, use a FieldListener inside of a GUI control somewhere in a Window.

1.2.1.4. Persistence

This sections allows to make the values of internal fields of a MacroModule persistent. It allows to specify a list of fully qualified field names as well as fields grouped by internal modules. In contrast of defining a field on the interface of the macro module, only its value is stored and restored, the persistent fields are not available on the macro module interface. A typical use case is making internal settings persistent.

Persistence {
    fields = FIELDLIST
    ...
    Module NAME {
      fields = FIELDLIST
      ...
    }
    ...
}

fields = FIELDLIST: defines the fields that are to be stored as a comma-separated list, typically modulename.fieldname (tag can be used multiple times).
Module = NAME: defines a section for fields of the given module (tag can be used multiple times) The fields given inside of the Module tag are given without the leading module name, since this is given by the section.

1.2.1.5. Deployment

This section allows to tell MeVisLab about dynamic dependencies of the module that are required when the module should be deployed to another computer. The ModuleDependencyAnalyzer module allows to find most dependencies automatically, but if you e.g., depend on other directories or if you add modules dynamically in your module, you need to specify these in the Deployment section.

Deployment {
    directory = PATH
    ...
    module = NAME
    ...
    DLL = NAME
    ...
}

directory = PATH: defines additional directory that this module depends on (tag can be used multiple times).
module = NAME: defines additional module that this module depends on (tag can be used multiple times).
DLL = NAME: defines additional DLL that this module depends on (tag can be used multiple times).

1.2.1.6. MLModule

Defines a module that contains an C++ image processing module that is derived from a Module in the ML.

Typically used tags can be found at Module.

Dynamic scripting: MLABMLModule

MLModule NAME {
  class         = NAME
  DLL           = NAME
  projectSource = PATH
  
  // tags from Module
}

class = NAME (default: same as MLModule NAME)

gives the name of the C++ module that should be created via the ML runtime system.

	Tip
	This can be used to have the same internal C++ class for a number of MeVisLab modules with different names and default values, or if you do not want the internal name to appear as the MeVisLab module name.

DLL = NAME

specify the dynamic load library that the C++ class for this module is defined in. The name is given without system-specific pre-/postfix.

Example: DLL = MLBase

projectSource = PATH

specify the path to the project sources. This optional tag is used to make the *.dsp file available in the module's context menu and the ModuleInspector. MeVisLab looks for the *.pro file of the name (projectSource)/(DLL).pro to create/update the dsp if needed.

This option should not be needed if a project is placed within a package that is known to MeVisLab. If the project is located at some different place, however, use this option with either an absolute or a relative path.

Example (relative): projectSource = $(LOCAL)/../../../../../Foo/Bar/MyProject

Example (absolute): projectSource = $(MLAB_MY_PACKAGE)/Sources/ML/MyProject

1.2.1.7. InventorModule

Defines a module that contains an C++ visualization module derived from an OpenInventor SoNode or SoEngine class.

Typically used tags can be found at Module.

Dynamic scripting: MLABInventorModule

InventorModule NAME {
  class          = NAME
  DLL            = NAME
  projectSource  = PATH
  hasGroupInputs = BOOL
  hasViewer      = BOOL
  hybridMLModule = BOOL
  
  // tags from Module
}

class = NAME (default: same as InventorModule NAME)

gives the name of the C++ module that should be created via the OpenInventor runtime system.

	Tip
	This can be used to have the same internal C++ class for a number of MeVisLab modules with different names and default values, or if you do not want the internal name to appear as the MeVisLab module name.

DLL = NAME

specify the dynamic load library that the C++ class for this module is defined in. The name is given without system-specific pre-/postfix.

Example: DLL = SoView2D

projectSource = PATH

see MLModule.

hasGroupInputs = BOOL (default: No)

defines if the module is derived from a SoGroup and should have dynamic SoNode inputs.

hasViewer = BOOL (default: No)

defines if the module should have a viewer (typically used on SoGroup derived nodes which should have an Inventor Viewer).

hybridMLModule = BOOL (default: No)

an InventorModule can contain a fully functional MLModule, whose fields appear as if they were the fields of the InventorModule. This is an advanced feature and should typically not be used.

1.2.1.8. MacroModule

Defines a macro module which can contain an internal network. Typically a MacroModule has an Interface section which defines the fields of the macro. The fields can be aliased from internal fields or standalone fields.

Typically used tags can be found at Module.

MacroModules should use the externalDefinition tag to define their Interface and Windows in an extra "ModuleName.script" file which should be named like the module itself.

If the externalDefinition tag is given, MeVisLab automatically loads the network with the same name and the extension ".mlab". If the module only contains scripting and does not require an internal network, use the scriptOnly tag to tell MeVisLab.

Dynamic scripting: MLABMacroModule

MacroModule NAME {
  scriptOnly             = BOOL
  onlyOneInstance        = BOOL
  applicationSplashImage = FILE
  
  // tags from Module
}

scriptOnly = BOOL (default: No): if set to 'Yes', no internal network is loaded/required.
onlyOneInstance = BOOL (default: No): if set to 'Yes', only one instance of this module can be started as an application, additionally created versions just show the already running application. This is used for applications that the user should only be able to start once.
applicationSplashImage = FILE: set a splash image that is shown on a splash screen when the application is started. This is nice for big applications that need some time to initialize all scripts etc.

1.2.1.9. FieldListener

The FieldListener listens to fields and calls the script command given in the command tag whenever the field changes.

The fields are given as the value tag and/or with multiple listenField tag.

There are two possible uses for a FieldListener:

They can be created in the Commands section of a Module.

They can be used anywhere in the control hierarchy of a Window.

1. If used in the Commands section, the FieldListener is active throughout the whole lifespan of a module instance (from creation to deletion) and reacts to any field changes whether there is an open module panel or not. Because of this, such a FieldListener cannot access the (controls of the) user interface of the module with scripting, just the fields of the module.

2. If used somewhere inside of a Window, the FieldListener is an invisible user interface element which is only active (and created) when the Window is actually created. Such a FieldListener can access all other user interface controls within that Window that are named using the ctx.control(name) Python or JavaScript function.

Note

Since part of a Window can be created multiple times using the Panel GUI control, multiple instances of the same FieldListener in a Window can exist at the same time and will all work and change the user interface via the ctx.control(name). The limitation to this is that only controls can be accessed that are also cloned by the Panel control, otherwise the ctx.control(name) function will return NULL. This means that you should put your FieldListeners (which are in the user interface) close to the GUI elements you are accessing so that they are also clone when a subpanel is extracted.

FieldListener [FIELD] {
  init        = BOOL
  callLater   = BOOL
  listenField = FIELD
  
  // ...
  
  command     = SCRIPT
}

listenField = FIELD

listen to the given field.

This tag can be used multiple times to listen to N fields with the same FieldListener

command = SCRIPT (arguments: changedField)

defines the script command that is executed when one of the fields changes. The changed field is passed as the first argument to the command.

init = BOOL (default: No)

if set to 'Yes', the command is triggered once when the FieldListener is created. The first of the fields it listens to is passed to the command.

	Tip
	This is especially useful when the FieldListener updates some user interface control and needs to be initiated initially to provide a correct user interface.

callLater = BOOL (default: No)

if set to 'Yes', the field listener is scheduled the next time the event loop is processed and not immediately when the field changes. You will only get one notification if multiple fields changed since the last event loop processing. If more than one field is listened to, the command is called without a field pointer, because the FieldListener does not know which of the fields have changed since the last event loop.

	Warning
	Be careful, setting callLater to 'Yes' can cause infinite loops of field notifications! Only use it when you know what you are doing!

1.3. GUI Controls

The following chapters give an overview of all possible GUI Controls and their tags. MeVisLab also contains a number of example MacroModules that demonstrate the individual features.

1.3.1. GUI Example Modules in MeVisLab

The following modules demonstrate the use of the most of the GUI controls. (This list may not be completely up-to-date, try searching for modules starting with Test* in the MeVisLab search.)

TestStyles - how to change the controls appearance (Colors,Fonts,...)
TestPrototypes - how to change tag defaults for given GUI controls
TestLayouter - showing the usage of AlignGroups
TestListView - showing a scripted ListView
TestModalDialog - how to create a modal dialog
TestHyperText - how to use RichText with hyper links
TestDefaultStyle - showing the default spacings etc.
TestComboBox - showing a scripted ComboBox
TestViewers - showing different Inventor viewers
TestInventorChildren - showing how to add inventor nodes dynamically
TestDynamicFrames - how to change Frame content via scripting
TestTable, TestVertical, TestSplitterLayout, TestHorizontal
TestFieldAccess - script access to field values, especially vectors, matrices and image properties
TestScriptUtils - showing the use of global script utility functions
TestTimers - how to create scripted timers

	Tip
	As an all-in-one example module, the ExampleGUIScripting module should be studied thoroughly.

1.3.2. Abstract GUI Controls

Abstract controls cannot be created directly in the MDL, but many concrete GUI controls are derived from these controls to provide their basic behavior/tags.

1.3.2.1. Control (Abstract)

Control is the base class for all GUI controls and provides a number of tags supported by every control. Some tags given here only make sense when used in the context of a layouter, e.g., colspan in Table or x/y in Grid.

Dynamic scripting: MLABWidgetControl

name      = NAME
panelName = STRING
expandX   = ENUM
expandY   = ENUM
stretchX  = INT
stretchY  = INT
visible   = BOOL
enabled   = BOOL
dependsOn = FIELDEXPRESSION
visibleOn = FIELDEXPRESSION

style     = NAME
styleSheetString = STRING
styleSheetFile   = FILE

w    = INT
h    = INT
pw   = INT
ph   = INT
mw   = INT
mh   = INT
maxw = INT
maxh = INT
fw   = INT
fh   = INT

// Control tags that are read by the owning layouter control:
alignX  = ENUM
alignY  = ENUM
x       = INT
y       = INT
x2      = INT
y2      = INT
colspan = INT
posX    = INT
posY    = INT
scale   = INT

// layouter tags for inter control alignment:
alignGroupX      = NAME // (alias: alignGroup = NAME)
alignGroupY      = NAME
childAlignGroupX = NAME // (alias: childAlignGroup = NAME)
childAlignGroupY = NAME
labelAlignGroup  = NAME

tooltip              = STRING
whatsThis            = STRING
droppedFileCommand   = SCRIPT
droppedObjectCommand = SCRIPT
acceptDrops          = BOOL
resizeCommand        = SCRIPT
initCommand          = SCRIPT
destroyedCommand     = SCRIPT

bgMode       = ENUM
editBgMode   = ENUM
buttonBgMode = ENUM

screenshotCommentCommand = SCRIPT

name = NAME (alias: instanceName): name of the control. The control is registered under this name and can be accessed from Python or JavaScript under this name. This is done by using the ctx.control("controlname") method.

style = NAME

defines the style to be used for this control (and for its children, if any).

Value	Meaning
`Fixed` (aliases: 0, No, False)	The control can never grow or shrink (e.g., the vertical direction of a button).
`Minimum`	The preferredWidth is minimal, and sufficient. The control can be expanded, but there is no advantage to it being larger (e.g., the horizontal direction of a button). It cannot be smaller than the preferredWidth.
`Maximum`	The preferredWidth is a maximum. The control can be shrunk any amount without detriment if other controls need the space (e.g., a separator line). It cannot be larger than the preferredWidth.
`Preferred`	The preferredWidth is best, but the control can be shrunk and still be useful. The control can be expanded, but there is no advantage to it being larger than preferredWidth (the default expandX value).
`Expanding` (aliases: 1, Yes, True)	The preferredWidth is a sensible size, but the control can be shrunk and still be useful. The control can make use of extra space, so it should get as much space as possible (e.g., the horizontal direction of a horizontal slider).
`MinimumExpanding`	The preferredWidth is minimal, and sufficient. The control can make use of extra space, so it should get as much space as possible (e.g., the horizontal direction of a horizontal slider).
`Ignored`	The preferredWidth is ignored. The control will get as much space as possible.

1.3.2.2. Frame (Abstract)

Frame is an abstract control which allows to set tags that control the frame appearance. A number of controls are derived from this control.

Frame is derived from Control.

Dynamic scripting: MLABFrameControl

frameShape        = ENUM
frameShadow       = ENUM
frameLineWidth    = INT
frameMidLineWidth = INT
frameMargin       = INT

frameShape = ENUM

shape of the frame, the possible values are:

NoFrame, Box, Panel, WinPanel, HLine, VLine, StyledPanel, PopupPanel, MenuBarPanel, ToolBarPanel, LineEditPanel, TabWidgetPanel, GroupBoxPanel, MShape

frameShadow = ENUM

shape of the frame, the possible values are:

Plain, Raised, Sunken, MShadow

frameLineWidth = INT: line width of the frame.
frameMidLineWidth = INT: mid line width.
frameMargin = INT: margin of border to frame.

1.3.2.3. Execute

Execute can be used to execute a script function anywhere in a GUI definition. It can be placed in any Control that supports children. It does not create a visible control but just executes the given scripting function which may be defined via the source tag in the Commands section of the module. For Python, it is also allowed to execute inline code that starts with "py:" (and for JavaScript, the line needs to start with "js:"). The given function can also be a child of an existing object written in dotted notation, e.g., "myObject.myFunction".

Execute = someFunction
Execute = "*js: MLAB.log("test") *"
Execute = "js: MLAB.log('test') "

The Execute statement has access to all controls that are "named" with the name tag and that appear BEFORE the Execute statement. Controls following after the Execute statement cannot be reached. An example for accessing a Control is given below.

	Note
	Generally it is not a good idea to use inline code, because it messes up your GUI interface. It is not possible to define your own functions and classes in the inline code, so you should prefer doing the scripting in external files given via source.

Label   = "Test" { name = mylabel }
Execute = "*js: ctx.control("label").setTitle("Title Changed"); *"

1.3.3. Layout Group Controls

The following controls group other control together and define how these child controls are laid out. Window is a special case, since it is the top level control and can only be declared on the top level of a module definition.

1.3.3.1. Window

Window is the base control that contains any other controls. A module can have any number of Windows in its MDL definition file. The first window (or the one with the name "_default") is used as the standard parameter panel of the module.

Window is derived from Control.

Dynamic scripting: MLABWindowControl

Window NAME {
  title              = STRING
  wakeupCommand      = SCRIPT
  shouldCloseCommand = SCRIPT
  maximized          = BOOL
  fullscreen         = BOOL
  borderless         = BOOL
  
  ANYGUICONTROL { }
  ...
}

title = STRING

title shown in the window title bar.

wakeupCommand = SCRIPT

command that is called when the window is shown, you should better use an Execute command, which is also called when your Window is extracted via a Panel control.

shouldCloseCommand = SCRIPT

command that is called when the window is closed by the user or by the program. If you do not want the window to be closed, you can call

ctx.window().setCloseAllowed(false)

within the script command. The default is that the window is closed.

maximized = BOOL (default: No)

the window will always be shown maximized on the screen.

fullscreen = BOOL (default: No)

the window will always be shown fullscreen, with no window bar decoration and close button.

borderless = BOOL (default: No)

the window will have no decoration at all, no close button etc.. Use with care because you cannot close such a window without adding your own close button to it.

ANYGUICONTROL

Controls defined inside the window are the content of the window. If more than one control is specified, the window automatically uses a TabView and the controls act as TabViewItems.

Example 1.1. Window

Have a look at the View3D.script (instantiate a View3D module in MeVisLab, right-click it and choose Related Files → View3D.script from the context menu). There, you will find four Window sections defined, namely 'View3D', 'Viewer', 'Settings' and 'LutEditor'. All these windows appear in the module's context menu under 'Show Window' below the separator. Above the separator, the default window (always called 'Panel') and the automatic panel are listed.

In the case of the View3D, no Window is named _default, so the first window ('View3D') is opened as the default panel on double-clicking the module.

Interface  {
  Inputs  {
    // ...
  }
  Outputs  {
    // ...
  }
  Parameters  {
    // ...
  }
} 

Description {
  // ...
}

Persistence {
  // ...
}

Commands  {
  source = $(LOCAL)/View3D.js
  wakeupCommand = wakeup

  ContextMenu {
    MenuItem "Show Inventor Inputs" { field = inventorInputOn }
  }
  FieldListener renderer.image {
    // ...
  }  
  // ...
}

Window View3D {
 // ...
}

Window Viewer {
  Viewer viewer.self {
    name  = viewer
    clone = No
  }
}

Window Settings {
  Panel {
    panel = Settings
  }
}

Window LutEditor {
  title = "Lut Editor"
  Vertical {
    Box Editor {
      Panel { 
        module = SoLUTEditor 
        panel  = editor
      }
    }
    Box Settings {
      Field SoLUTEditor.relativeLut        { }
      Field SoLUTEditor.alphaFactor        { slider = Yes }
      Field SoLUTEditor.colorInterpolation { }
    }
    Box Range {
      Panel { 
        module = SoLUTEditor 
        panel  = range
      }
    }
  }
}

1.3.3.2. Vertical

Vertical is a vertical layout group control. Each control inside of the Vertical is laid out according to its size requirements.

The following children's tags are taken into account:

stretchY, expandY

Vertical is derived from Frame.

Aliases: VerticalNB, Category

Dynamic scripting: MLABVBoxControl

Vertical {
  spacing = INT
  margin  = INT
  
  // Additional tags: see Frame
  
  ANYGUICONTROL { }
  ...
}

spacing = INT: spacing between the controls.

margin = INT: spacing between border and controls.

ANYGUICONTROL: all controls declared inside of the group are automatically children of the group.

Example 1.2. Vertical

Have a look at the module TestVerticalLayout. This module features some GUI components that are arranged vertically.

Figure 1.1. TestVerticalLayout Module

1.3.3.3. Horizontal

Horizontal is a horizontal layout group control. Each control inside of the Horizontal is laid out according to its size requirements.

The following children's tags are taken into account:

stretchX, expandX

Horizontal is derived from Frame.

Aliases: HorizontalNB, ButtonGroup

Dynamic scripting: MLABHBoxControl

Horizontal {
  spacing = INT
  margin  = INT
  
  // Additional tags: see Frame
  
  ANYGUICONTROL { }
  ...
}

spacing = INT: spacing between the controls

margin = INT: spacing between border and controls

ANYGUICONTROL: all controls declared inside of the group are automatically children of the group.

Example 1.3. Horizontal

Have a look at the module TestHorizontalLayout. This module features some GUI components that are arranged horizontally.

Figure 1.2. TestHorizontalLayout Module

1.3.3.4. Table

Table organizes its children in rows. Child controls can span multiple columns and can be aligned within their row/column position.

Each control inside of the Table is laid out according to its size requirements, the following children tags are used by the layouter:

stretchX/Y, expandX/Y, alignX/Y, colspan

Table is derived from Frame.

Dynamic scripting: MLABTableControl

Table {
  spacing = INT
  margin  = INT
  
  // Additional tags: see Frame
  
  Row {
    ANYGUICONTROL { }
    ...
  }
  Row {
    ANYGUICONTROL { }
    ...
  }
  ...
}

spacing = INT: spacing between the controls.

margin = INT: spacing between border and controls.

Row: specifies a row in the table. The row can contain any number of child controls, which can also span multiple column (with the colspan tag used in a control).

Example 1.4. Table

Have a look at the module TestTableLayout. Below you will find the MDL code that defines this example macro module.

scriptOnly = Yes

Window {
  title = "GUITest: Table"

  Table {
    margin  = 5
    spacing = 3

    Row {
      Button {
        colspan = 3
        title   = "TopLeft 3"
        expandX = Yes
        expandY = Yes
      }

      Button {
        colspan = 2
        title   = "TopRight 2"
        expandX = Yes
        expandY = Yes
      }
    }

    Row {
      Button {
        colspan = 2
        title   = "MidLeft 2"
        expandX = Yes
        expandY = No
      }

      Button {
        colspan = 1
        title   = "MidCenter 1"
        expandX = No
        expandY = Yes
      }

      Button {
        colspan = 2
        title   = "MidRight 2"
        expandX = Yes
        expandY = No
      }
    }

    Row {
      Button {
        colspan = 2
        title   = "BottomLeft 2"
        expandX = Yes
        expandY = Yes
      }

      Button {
        colspan = 3
        title   = "BottomRight 3"
        expandX = Yes
        expandY = Yes
      }
    }

    Row {
      Label "Resize this Window!" { 
        colspan = 5
        alignX  = Center
      }
    }
  } // wrap
} // Window

Figure 1.3. TestTableLayout Module

1.3.3.5. Grid

Grid organizes its children in rows and columns. Child controls can be positioned at any row/column position and can span multiple columns and can be aligned within their row/column position.

Each control inside of the Grid is laid out according to its size requirements, the following children tags are used by the layouter:

stretchX/Y, expandX/Y, alignX/Y, x, y, x2, y2

Grid is derived from Frame.

Dynamic scripting: MLABGridControl

Tip

Each child control needs to have a x/y position tag.

In contrast to Table, where controls are automatically ordered in rows, the Grid allows more complex positioning.

Grid {
  spacing = INT
  margin  = INT
  
  // Additional tags: see Frame
  
  // simple control:
  ANYGUICONTROL { x = INT y = INT }
  
  // multicolumn control:
  ANYGUICONTROL { x = INT y = INT x2 = INT y2 = INT }
  ...
}

spacing = INT: spacing between the controls.

margin = INT: spacing between border and controls.

ANYGUICONTROL: specifies a child control (which is positioned at the row and column given by the x and y tags in the Grid), either as a row in the table, the row can contain any number of child controls, which can also span multiple column (with the colspan tag used in a control).

Example 1.5. Grid

Have a look at the module TestGridLayout. Below you will find the MDL code that defines this example macro module.

scriptOnly = yes

Window {
  title = "GUITest: Grid"

  Grid {
    margin  = 5
    spacing = 3

    Button {
      x  = 0
      y  = 0
      x2 = 2
      Y2 = 0
      title   = "<0,0>-<2,0>"
      expandX = Yes
      expandY = Yes
    }

    Button {
      x  = 3
      y  = 0
      x2 = 3
      y2 = 2
      title   = "<3,0>-<3,2>"
      expandX = Yes
      expandY = Yes
      alignX = Right
    }

    Button {
      x = 0
      y = 1
      title   = "<0,1>"
      expandX = Yes
      alignX  = Left
    }

    Button {
      x = 1
      y = 1
      title   = "<1,1>"
      expandY = Yes
      alignY  = Top
    }

    Button {
      x  = 2
      y  = 1
      x2 = 2
      y2 = 2
      title   = "<2,1>-<2,2>"
      expandX = Yes
      expandY = Yes
    }

    Button {
      x  = 0
      y  = 2
      x2 = 1
      y2 = 3
      title   = "<0,2>-<1,3>"
      expandX = Yes
      expandY = Yes
    }

    Button {
      x  = 2
      y  = 3
      x2 = 3
      y2 = 3
      title   = "<2,3>-<3,3>"
      expandX = Yes
      expandY = Yes
      alignY  = Bottom
    }
  } // Grid
} // Window

Figure 1.4. TestGridLayout Module

1.3.3.6. ButtonBox

ButtonBox is a control that presents Button controls in a layout that is appropriate for the operating system's look & feel. Dialogs typically present buttons in a layout that conforms to the interface guidelines for that platform. A ButtonBox automatically uses the appropriate layout of the user's desktop environment, and may change the order in which the child buttons appear.

Dynamic scripting: MLABButtonBoxControl

ButtonBox {
  orientation = ENUM
  
  // Button control:
  Button { role = ENUM }
  ...
}

orientation = ENUM (default: Horizontal)

the orientation of the button box.

Possible values: Horizontal, Vertical

Button

specifies a Button control. The role attribute of a Button is used to determine the role of the button within a dialog window. See Button control for possible values.

If the button does not specify a role, the button title will be evaluated for know role strings. Currently known strings are: Ok, Open, Save, Cancel, Close, Discard, Apply, Reset, Restore Defaults, Help, Save All, Yes, Yes To All, No, No To All, Abort, Retry, Ignore

1.3.3.7. Splitter

Splitter organizes its children in vertical or horizontal direction and allows to resize the contained controls with draggable handles. The color and shadow of the splitter are customizable.

Each control inside of the Splitter is laid out according to its size requirements. The following children tags are used by the layouter:

stretchX/Y, expandX/Y

Splitter is derived from Frame.

Dynamic scripting: MLABSplitterControl

Splitter {
  direction = ENUM
  color     = COLOR
  shadow    = ENUM
  
  // Additional: tags for frame
  
  ANYGUICONTROL { }
  ...
}

direction = ENUM

defines layout direction of the Splitter.

Possible values: Vertical, Horizontal

color = COLOR

the color which the splitter should have.

shadow = ENUM

the shadow of the splitter. Possible values are Plain, Raised and Sunken.

Example 1.6. Splitter

Have a look at the module TestSplitterLayout. Below you will find the MDL code that defines this example macro module.

scriptOnly = Yes

Window {
  title = "GUITest: Splitter"
  w     = 512
  h     = 384

  Splitter {
    direction = Vertical

    Button {
      title   = "1"
      expandX = Yes
      expandy = Yes
    }

    Splitter {
      direction = Horizontal

      Button {
        title   = "2"
        expandX = Yes
        expandy = Yes
      }

      Splitter {
        direction = Vertical

        Button {
          title   = "3"
          expandX = Yes
          expandy = Yes
        }

        Splitter {
          direction = Horizontal
  
          Button {
            title   = "4"
            expandX = Yes
            expandy = Yes
          }

          Splitter {
            direction = Vertical
    
            Button {
              title   = "5"
              expandX = Yes
              expandy = Yes
            }

            Splitter {
              direction = Horizontal
    
              Button {
                title   = "6"
                expandX = Yes
                expandy = Yes
              }

              Splitter {
                direction = Vertical
    
                Button {
                  title   = "7"
                  expandX = Yes
                  expandy = Yes
                }
              }
            }
          }
        }
      }
    }
  } // Splitter
} // Window

Figure 1.5. TestSplitterLayout Module

1.3.3.8. Box

Box shows a frame with a title around its children. It can contain any inner layout, which is selected by the layout tag. If no layout is chosen, a Vertical is implicitly used.

Box is derived from Frame.

Dynamic scripting: MLABBoxControl

Box STRING {
  title          = STRING
  alignTitle     = ENUM
  layout         = NAME
  checked        = BOOL
  checkable      = BOOL
  checkedField   = FIELD
  
  // Additional: tags for frame
  
  ANYGUICONTROL { }
  ...
}

title = STRING

overwrite the title given in Box tag.

alignTitle = ENUM (default: Left)

set alignment of the title.

Possible values: Left, Center, Right

layout = NAME (default: Vertical)

selects a layouter.

Possible values: Vertical, Horizontal, Table, Grid, Splitter, FreeFloat

checkedField = FIELD

checkedField can be a boolean field. Its value is used to toggle the checked state, which enables/disables the content of the box.

checkable = BOOL

if checkable is 'Yes', then a checkbox appears in the box title, which enables/disables the content of the box.

checked = BOOL

checked is used to set the checked state, which indicates if the content of the box is enabled or disabled. This attribute will be overwritten if checkedField is given.

Note: There is a known Qt bug that causes the box contents to overlap with the checkbox, if the box has no title

Example 1.7. Box

Have a look at the module TestBoxLayout. Below you will find the MDL code that defines this example macro module.

scriptOnly = yes

Window {
  title = "GUITest: Box"

  Vertical {
    margin  = 5

    Label "A Box with title and automatic layout:" {}
    Box BoxTitle {
       spacing = 5
       margin  = 5
       Button { title = "A Button" }
       Button { title = "B Button" }
       Button { title = "C Button" }
    }
    
    Label "A Box without title and grid-layout:" {}
    Box {
       spacing = 2
       margin  = 2
       layout = Grid

       Button { title = "A Button" x = 2 y = 0}
       Button { title = "B Button" x = 1 y = 1}
       Button { title = "C Button" x = 0 y = 2}
    }
  } // Vertical
} // Window

Figure 1.6. TestBoxLayout Module

1.3.3.9. ScrollView

ScrollView allows to scroll a bigger control with vertical and horizontal scrollbars. If not layout is specified, the internal layout is a Vertical layout.

ScrollView is derived from Frame.

Dynamic scripting: MLABScrollViewControl

ScrollView {
  layout    = NAME
  hscroller = ENUM (Default: Auto) // Auto|On|Off horizontal scrollbar mode
  vscroller = ENUM (Default: Auto) // Auto|On|Off vertical scrollbar mode
  
  // Additional: tags for frame
  
  ANYGUICONTROL { }
  ...
}

hscroller = ENUM (default: Auto)

sets if the horizontal scrollbar is always on, off or should only appear when needed (auto).

Possible values: Auto, On, Off

vscroller = ENUM (default: Auto)

sets if the vertical scrollbar is always on, off or should only appear when needed (auto).

Possible values: Auto, On, Off

layout = NAME (default: Vertical)

selects a layouter.

Possible values: Vertical, Horizontal, Table, Grid, Splitter, FreeFloat

Example 1.8. ScrollView

The following example adds another window to the View3D which then becomes available via the module's context menu (Show Window). It adds the settings panel in a ScrollView with no horizontal scroller but a vertical scroller if the panel's content exceeds the window (which it does).

Window ScrollViewTest {
  ScrollView {
  
    hscroller = Off
    vscroller = Auto
    
    Panel {
      panel = Settings
    }    
  }
}

Figure 1.7. ScrollView Example

1.3.3.10. TabView

TabView shows a TabBar and contains a stack of controls that are visible depending on the selected Tab. It also offers a mode where the TabBar is not visible, allowing to change the selected Tab by scripting only (this is often used in applications, which group their panels inside an invisible TabView).

The child controls of the TabView can be any controls. The additional tags needed for the TabView are given as extra tags to the child controls. Refer to TabViewItem to see what tags are available.

The selected tab can be changed by using the selectTabAtIndex(int) or selectTab(controlname) method on the TabView.

TabView is derived from Control.

Dynamic scripting: MLABTabViewControl

 TabView {
  mode = ENUM
  
  ANYGUICONTROL { }
  ...
}

mode = ENUM (default: normal)

selects if the TabBar is visible and if it is on the top or bottom of the widget. If the mode is "toolbox", a ToolBox widget is used instead of a TabView; this has the advantage of internal scrollbars and the possibility of long tab description.

Possible values: Normal, Top, Bottom, Left, Right, Invisible, Toolbox

ANYGUICONTROL

each control in the TabView is treated as a TabViewItem and can contain the tags given in TabViewItem

Example 1.9. TabView

Have a look at the module TestTabViewLayout. This module features the use of an invisible TabView where the tabs are changed by using scripting commands that are triggered by pressing a button, and the use of standard tabs.

Note that each direct child of a TabView is turned into an own tab.

scriptOnly = yes

Commands {
  source = $(LOCAL)/TestTabViewLayout.js
}

Window {
  title = "GUITest: TabViews"
  
    Vertical "TabView with invisible Tabs" {
      Box Select {
        layout = Horizontal
        Button {  title = "Boxes"    command = switchTab0 }
        Button {  title = "Table"    command = switchTab1 }
        Button {  title = "TextView" command = switchTab2 }
      }

      TabView {
        name = TabViewInvisible
        mode = Invisible

        Vertical {
          tabTitle = "Boxes"
          margin  = 5

          Box BoxTitle { ... }

          Label "A Box without title and grid-layout:" {}
          
          Box BoxTitle { ...  }
          
        } // Vertical


        Table { ... } 
        
        TextView {
          tabTitle = TextView
          title    = TextViewExample
          text     = "Example for a TextView-Control in a TabView"
        } // TextView
      } // TabView
    }    
    
    TabView "TabView with visible Tabs" {
        Vertical "Boxes" {
          margin  = 5

          Box BoxTitle { ... }

          Label "A Box without title and grid-layout:" {}

          Box BoxTitle { ... }
          
        } // Vertical

        Table "Table" { ... }
        
    } // Horizontal
} // Window

Figure 1.8. TestTabViewLayout Module

1.3.3.10.1. TabViewItem

The TabViewItem can be used inside of a TabView to specify the TabView entries. Any other control can also act as a TabViewItem in the TabView, just add the tags below to the control to pass the needed information to the TabView.

The TabViewItem is a Vertical layouter and has the following tags:

Dynamic scripting: MLABVBoxControl

TabViewItem STRING {
  tabIcon    = FILE             // Icon for tab title
  tabTitle   = STRING           // Extra title for tab (instead of TITLE)
  tabInitial = BOOL             // Initial tab selection (when 'Yes')
  tabTooltip = STRING           // Tooltip for the tab item
  
  tabSelectedCommand   = SCRIPT // Called whenever this tab is selected
  tabDeselectedCommand = SCRIPT // Called whenever this tab is deselected
  
  tabEnabled = BOOL             // Enable/disable this Tab
  
  ANYGUICONTROL { }
  ...
}

tabIcon = FILE: icon to show on the TabBar.
tabTitle = STRING: title to use in the TabBar (overwrites the value of the TabViewItem tag).
tabInitial = BOOL: selects a TabViewItem as the initially selected Tab (otherwise the first Tab is selected).
tabTooltip = STRING: tool tip on the TabBar.
tabSelectedCommand = SCRIPT: script command that is called when this TabViewItem is selected (also called on the initial selection).
tabDeselectedCommand = SCRIPT: script command that is called when this TabViewItem is deselected.
tabEnabled = BOOL: Enable or disable this Tab initially.

1.3.3.11. FreeFloat

FreeFloat organizes its children at a given integer position. The coordinate system starts with (0,0) in the upper left corner.

Each control inside of the FreeFloat is positioned with the tags:

posX/Y

The size of the controls is taken from the width/height tags:

w/h

FreeFloat is derived from Frame.

Dynamic scripting: MLABFreeFloatControl

	Tip
	The FreeFloat should ONLY be used where no other layouter works, since it offers fixed control positioning, which can have undesired effects when the font size etc. changes. It can be used nicely to have a title image and some floating buttons on the image.

FreeFloat {
  autoSize = BOOL
  
  // Additional: tags for frame
  
  ANYGUICONTROL { }
  ...
}

autoSize = BOOL (default: Yes): sets if the FreeFloat automatically calculates its preferred size as the bounding box of all contained controls.

1.3.4. User Input GUI Controls

User input control are typically tightly coupled with field in MeVisLab, thus allowing an easy way to represent a module's parameter field with a desired user interface. If not stated, all controls are derived from Control and offer its tags.

1.3.4.1. Field

Field is a very generic control that can show any of the fields in MeVisLab as an editable GUI element. It typically shows a label with the field name (or a given title) followed by a number of user-editable controls, e.g., LineEdit, NumberEdit, VectorEdit, ColorEdit, Slider etc.

It also allows to have field connections by using drag-and-drop of the title label and a pop-up menu to work on the underlying field. Whether drag-and-drop is turned on depends on the window the control is used in. If it is an application window, drag-and-drop is automatically disabled.

Dynamic scripting: MLABFieldControl

Field FIELD {
  title                 = STRING
  titleField            = FIELD
  edit                  = BOOL
  slider                = BOOL  
  pressedIndicatorField = FIELD  
  editField             = BOOL
  format                = STRING
  minLength             = INT
  hintText              = STRING
  trim                  = ENUM
  sunkenVectorLabels    = BOOL
  editAlign             = ENUM
  textAlign             = ENUM
  step                  = FLOAT
  stepstep              = FLOAT
  sliderSnap            = FLOAT
  spacing               = INT
  alignGroup            = STRING
  enumAutoFormat        = BOOL
  comboBox              = BOOL
  comboCompletes        = BOOL
  comboSeparator        = STRING
  comboField            = FIELD
  
  comboItems {
    item {
      image = FILE
      title = STRING
    }
    ...
  }
  applyButton           = BOOL
  browseButton          = BOOL
  browseMode            = ENUM
  browseTitle           = STRING
  browseFilter          = STRING
  browseSelectedCommand = SCRIPT
  useSheet              = BOOL
  fieldDragging         = BOOL
  updateFieldWhileEditing = BOOL
}

title = STRING

title shown on field label.

titleField = FIELD

the title can also be given by a field, it is automatically updated when the field changes and shows the field's string value.

step = FLOAT

step value used for NumberEdits.

stepstep = FLOAT

stepstep value used for NumberEdits.

sliderSnap = FLOAT

If set to a value != 0, the slider always snaps to a value which is multiples of this value starting at the sliders minimum.

edit = BOOL (default: Yes)

allow editing of the fields value. If turned to 'No', typically text labels are used instead of editable GUI elements.

(This is different from the general Control tag enabled, which enables or disables a whole control (also called "grayed out").)

slider = BOOL (default: No)

turns on/off a slider. This only works if the field is a number field and has min and max values.

pressedIndicatorField = FIELD

The Field needs to be a BoolField. It is set to true if the user presses the slider button and to false if the user releases the slider button.

editField = BOOL (default: Yes)

turns on/off the editable GUI element, typically is used to enable the slider without the NumberEdit to the left.

format = STRING

format to be printed as in sprintf, e.g., %4.5f or %x

	Note
	You have to use the right %d,%x ,%f,%g type for float/double/int fields.

minLength = INT

minimum width of characters reserved in the editable GUI element.

hintText = STRING

Hint text shown in editable line edit if line edit is empty and doesn't have the focus.

updateFieldWhileEditing = BOOL (default: False)

Sets if the attached field is updated while the user types text in the line edit.

trim = ENUM (default: None)

does trimming on the string when it is not edited.

Possible values: Left, Center, Right, None

Left: "...LongText"

Center: "Long...Text"

Right : "LongText..."

None: No trimming

sunkenVectorLabels = BOOL (default: Yes)

if yes, draw labels into the same frame as the LineEdit, otherwise draw them separate.

editAlign = ENUM

alignment of the text in the Line/NumberEdits. Default depends on whether numbers or strings are edited.

Possible values: Left, Right, Center

textAlign = ENUM (default: left)

alignment of the text in the title label.

Possible values: Left, Right, Center

alignGroup = STRING

gives a hint to which other Fields this Field should be aligned. If the Control should never be aligned, use "none". This is a general feature and is explained in detail in Section 1.3.9.1, “Align Groups”

enumAutoFormat = BOOL (default: Yes)

for enum fields you can set this to 'No' to avoid automatic formatting of enum names. Automatic formatting means that a field called "MyName" receives the automatic title "My Name". If the enum items have a common prefix, then this is also stripped when automatic formatting is active.

comboBox = BOOL (default: No)

turn on comboBox instead of LineEdit.

comboCompletes = BOOL (default: Yes)

turn on auto complete when editable.

comboField = FIELD

a field whose string value is used instead of given comboItems. When the comboField changes, the available combo list is updated.

comboSeparator = STRING (default: ",")

string value to use for splitting the string value of comboField into individual values.

comboItems

specify the items shown in the ComboBox, may be omitted if comboField is given.

Each item is specified with the item tag.

Each item entry can contain the following tags:

image = FILE: image to be used for the item
title = STRING: title to be used for the item

applyButton = BOOL

only for VectorEdit. Typically only Rotation has an Apply Button automatically, otherwise it is off by default.

browseButton = BOOL

switch on an additional browse button that opens a file dialog at current field value (path).

browseMode = ENUM (default: Open)

select the type of the file dialog.

Possible values: Open, Save, Directory

browseTitle = STRING

the Title of the button for the file dialog

browseFilter = STRING

the file extension filter that is used in open and save mode. You can specify the file types as follows:

browseFilter = "All C++ files (*.cpp *.cc *.C *.cxx *.c++);;Text files (*.txt);;All files (*)"

Filters are separated by double-semicolon. The filter is a space-separated list of glob-style expressions enclosed in braces that follow the textual description of the filter.

browseSelectedCommand = SCRIPT

script to evaluate when the user made a selection with the file dialog.

useSheet = BOOL (default: Yes)

create any attached dialog (e.g., file dialog) as sheet on Mac OS X. A sheet is a modal dialog attached to a particular document or window.

spacing = INT

set the internal spacing between the GUI elements of a FieldControl.

wrap = BOOL

if set to 'Yes' and FIELD has min/max value, then step and stepstep wrap the value around when reaching the boundaries.

fieldDragging = BOOL

enables/disables the possibility to drag the fields label onto other field label to create connections. The default is 'Yes' for normal panels and 'No' for standalone applications. This also turns on the connection icons and enables the field context menu on field labels.

// Different layouts can be used with certain types of fields:
//        
// MLABStringField:
// ----------------
// FieldLabel | <- LineEdit -> | [Browse/Save Button]
//
// If "edit" is 'No', LineEdit is just a Label
//
// MLABBoolField:
// ----------------
// FieldLabel | CheckBox
// (CheckBox is without label on right)
//
// MLABInt/Float/DoubleField:
// --------------------------
// FieldLabel | NumberEdit | [<- Slider if min/max is set and "slider" tag is 'Yes' ->]
//
// If "edit" is 'No', NumberEdit is just a Label
//
// MLABEnumField:
// --------------
// FieldLabel | ComboBox
//
// MLABTriggerField:
// --------------
// FieldLabel | Button
//
// MLABColorField:
// --------------
// FieldLabel | ColorEdit
//
// MLABVec2f/3f/4f/Plane/RotationField:
// ------------------------------------------
// FieldLabel | x | NumberEdit | y | NumberEdit | z | NumberEdit | d | NumberEdit | [Apply Button]
//
// Naming for labels:
// MLABVec2f: x,y
// MLABVec3f: x,y,z
// MLABVec4f: x,y,z,t
// MLABRotation: x,y,z,r
// MLABPlane: x,y,z,d
//
// If "edit" is 'No', NumberEdits are just Labels

1.3.4.2. FieldLabel

FieldLabel shows the draggable label that is used in the Field control. It may be used if one wants to allow a drag/drop connection, e.g., of a matrix, and does not want to show the value of the field.

FieldLabel FIELD {
  title      = STRING
  titleField = FIELD
}

title = STRING: title shown on field label.
titleField = FIELD: the title can also be given by a field. It is automatically updated when the field changes and shows the field's string value.

1.3.4.3. Button

Button shows a clickable button that can either trigger a MLABTriggerField or MLABBoolField or that can call a script given as command tag. The button can have multiple images for the different states and it can be a normal or a toggle button.

Dynamic scripting: MLABButtonControl

	Tip
	You can use & in the button title to add an ALT keyboard shortcut binding to a button. The respective letter will be underlined (e.g., "&Ok").

Button [FIELD] {
  title            = STRING
  titleField       = FIELD
  role             = ENUM
  image            = FILE
  accel            = KEYSEQUENCE
  border           = BOOL
  autoRepeat       = BOOL
  normalOnImage    = FILE
  normalOffImage   = FILE
  activeOnImage    = FILE
  activeOffImage   = FILE
  disabledOnImage  = FILE
  disabledOffImage = FILE
  globalStop       = BOOL
  
  popupMenu {
    // See definition of SubMenu
  }
  
  command = SCRIPT
}

title = STRING

title on the button.

titleField = FIELD

the title can also be given by a field. It is automatically updated when the field changes and shows the field's string value.

role = ENUM (default: ActionRole)

describes the role of the button in the window/dialog. It is evaluated if the button has been placed within a ButtonBox container.

Possible values are:

AcceptRole: Clicking the button causes the dialog to be accepted (e.g., OK).
RejectRole: Clicking the button causes the dialog to be rejected (e.g., Cancel).
DestructiveRole: Clicking the button causes a destructive change (e.g., for Discarding Changes) and closes the dialog.
ActionRole: Clicking the button causes changes to the elements within the dialog.
HelpRole: The button can be clicked to request help.
YesRole: The button is a "Yes"-like button.
NoRole: The button is a "No"-like button.
ApplyRole: The button applies current changes.
ResetRole: The button resets the dialog's fields to default values.

image = FILE

specify a pixmap to use on the button.

accel = KEYSEQUENCE

a CTRL or ALT key sequence that activates this button. For normal ALT keyboard shortcuts, use the & notation in the title string.

Example:

accel = Ctrl+U

border = BOOL (default: Yes)

switches the buttons border on/off.

autoRepeat = BOOL (Default: No)

flag if button sends repeated clicked signal when user holds button.

normalOnImage = FILE

normalOffImage = FILE

activeOnImage = FILE

activeOffImage = FILE

disabledOnImage = FILE

disabledOffImage = FILE

you may specify different images for all states of the button.

popupMenu

define a pop-up menu to show on button press.

globalStop = BOOL (default = No)

defines that this button can be used as a global stop button, so that current ML calculations can be stopped by clicking this button.

To check buttons for a stop request in the scripting, you have to call MLAB.shouldStop() regularly in you scripting loop. This returns true if a stop button was pressed.

command = SCRIPT

script that is executed when the button is pressed/toggled.

1.3.4.4. ToolButton

ToolButton is a quick access button which is typically used in ToolBars. It can have an additional pop-up menu that pops up after a given delay. It has mainly the features from Button, but additionally supports autoRaise, which lets the border be highlighted when the mouse moves over it. The title is typically not shown. It can either trigger a MLABTriggerField or MLABBoolField or can call a script given as command tag. The button can have multiple images for the different states and it can be a normal or a toggle button.

Dynamic scripting: MLABToolButtonControl

ToolButton [FIELD] {
  image                 = FILE
  title                 = STRING
  textPosition          = ENUM
  autoRepeat            = BOOL
  autoRaise             = BOOL
  autoScale             = BOOL
  accel                 = KEYSEQUENCE
  scaleIconSetToMinSize = BOOL
  normalOnImage         = FILE
  normalOffImage        = FILE
  activeOnImage         = FILE
  activeOffImage        = FILE
  disabledOnImage       = FILE
  disabledOffImage      = FILE
  globalStop            = BOOL
  
  popupMenu {
    // See definition of SubMenu
  }
  popupDelay = FLOAT
  
  command    = SCRIPT
}

title = STRING

title on the button (typically not shown).

image = FILE

specify a pixmap to use on the button.

textPosition = ENUM (default: Bottom)

position of the title, relative to the image.

Values: Right, Bottom

accel = KEYSEQUENCE

a CTRL or ALT key sequence that activates this button. For normal ALT keyboard shortcuts, use the & notation in the title string.

Example:

accel = Ctrl+U

autoRepeat = BOOL (default: No)

flag if button sends repeated clicked signal when user holds button.

autoRaise = BOOL (default: No)

show the border only on mouse over.

autoScale = BOOL (default: No)

scale the images to the MeVisLab global default tool button size.

scaleIconSetToMinSize = BOOL (default: No)

If autoScale is set to 'Yes' and this tag is also set to 'Yes', the Images from the following six ImageTags are not scaled to the default tool button size but to the minimum size of the tool button as set by the tags mw and mh:

normalOnImage = FILE

normalOffImage = FILE

activeOnImage = FILE

activeOffImage = FILE

disabledOnImage = FILE

disabledOffImage = FILE

You may specify different images for all states of the button.

popupMenu

define a pop-up menu to show on button press.

popupDelay = FLOAT

delay to show the pop-up.

Set this to 0.01 or smaller to disable the delay. Values above will result in the default value for the platform (legacy support).

globalStop = BOOL (default = No)

defines that this button can be used as a global stop button, so that current ML calculations can be stopped by clicking this button.

To check buttons for a stop request in the scripting, you have to call MLAB.shouldStop()regularly in you scripting loop. This returns true if a stop button was pressed.

command = SCRIPT

script that is executed when the button is pressed/toggled.

1.3.4.5. ButtonBar

ButtonBar is a control that has different appearances for a given number of entries being read from an enum field or integer field. It can be vertically or horizontally laid out. It is synchronized with the field bidirectionally.

Available modes are:

- a group of Buttons with icons and/or titles

- a group of RadioButtons with icons and/or titles

- a ComboBox that shows a pop-up bar showing the possible options as items. Items are given as list of items in the items tag group. Each item either gives an enum string value or an integer number. If no items are given for an enum field, all enums are automatically shown with their titles.

Dynamic scripting: MLABButtonBarControl

	Tip
	If you use the radio value for the `show` mode, you can generate nice one-of-many radio groups.

ButtonBar FIELD {
  show              = ENUM
  enumAutoFormat    = BOOL
  direction         = ENUM
  border            = BOOL
  showItemInternals = BOOL
  title             = STRING
  strips            = INT
  autoScale         = BOOL
  
  items {
    item [NAME|VALUE] {
      image            = FILE
      title            = STRING
      tooltip          = STRING
      whatsThis        = STRING
      accel            = KEYSEQUENCE
      normalOnImage    = FILE
      normalOffImage   = FILE
      activeOnImage    = FILE
      activeOffImage   = FILE
      disabledOnImage  = FILE
      disabledOffImage = FILE
    }
    ...
  }
}

show = ENUM (default: all)

how the ButtonBar should show its items.

Possible values: One, All, Radio, Toolbuttons

"one" shows the pop-up menu, "all" shows all entries as buttons, "radio" shows radio buttons and "toolbuttons" shows tool buttons.

direction = ENUM (default: Horizonal)

layout direction of the buttons.

Possible values: Vertical,Horizontal

border = BOOL (default: Yes)

if buttons should have a border (not selectable in all show options).

showItemInternals = BOOL (default: No)

show internal name of items.

title = STRING

title of ButtonGroup frame, if any (if used, implicitly sets border = True).

strips = INT (default: 1)

sets number of "strips" in which the buttons are organized.

spacing = INT (default: 4)

sets spacing between buttons (not used in all show options).

autoScale = BOOL (default: No)

scale the images of toolbuttons to the MeVisLab global default tool button size.

enumAutoFormat = BOOL (default: Yes)

for enum fields you can set this to 'No' to avoid automatic formatting of enum names.

items

specify the items shown in the ButtonBar. If not specified, uses items from enum field automatically.

Each item is specified with the item tag, which need to have a string value for an enum field and an integer for an integer field.

Each item entry can hold the following tags:

image = FILE: image to be used for the item.
title = STRING: title to be used for the item. To have a toolbutton that only shows its icon, set this explicitly to an empty string.
tooltip = STRING: set tool tip shown on the item (for the pushbutton, radiobuttons).
whatsThis = STRING: set whatsThis text of item (for the pushbutton, radiobuttons).
accel = STRING: set accelerator key for this item.
normalOnImage = FILE
normalOffImage = FILE
activeOnImage = FILE
activeOffImage = FILE
disabledOnImage = FILE
disabledOffImage = FILE: images specifying details depending on the state of the buttons (not supported in all show modes).

// Integer field as radio buttons
ButtonBar someIntField {
  show      = Radio
  direction = Vertical
  title     = "Select child"
  items {
    item -1 { title = "Auto"    }
    item  0 { title = "Child 0" }
    item  2 { title = "Child 2" }
    item  4 { title = "Child 4" }
  }
}
// Enum field as buttons
ButtonBar someEnumField {
  show      = All
  direction = Vertical
  items {
    item "ADD"      { image = $(LOCAL)/add.png [title= ...]}
    item "SUBTRACT" { image = $(LOCAL)/subtract.png        }
    item "BLEND"    { image = $(LOCAL)/blend.png           }
  }
}

1.3.4.6. CheckBox

CheckBox is a check box with a label or image to the right. It can be synchronized with an MLABBoolField or MLABIntegerField. If a Field is given, the label of the Checkbox also supports drag-and-drop the same way as Field-Controls.

Dynamic scripting: MLABCheckBoxControl

	Tip
	A CheckBox is used to implement a many-of-many choice, while a one-of-many choice is done with a ButtonBar (especially the radio option) or a ComboBox

CheckBox [FIELD] {
  title = STRING
  image = FILE
  edit = BOOL
}

title = STRING

label next to the checkbox (RichText).

image = FILE

specify a pixmap to use next to the checkbox.

edit = BOOL (default: Yes)

allow editing of value. If turned to 'No' the value is not editable, but the text is displayed normal.

(This is different from the general Control tag enabled, which enables or disables a whole control (also called "grayed out").)

1.3.4.7. ComboBox

ComboBox is a control that allows a string to be edited and also supports a pop-up of possible values. If editing is disabled, only selecting a preset is possible. For enum fields, you should use a ButtonBar instead. If the ComboBox has a given field, it is synchronized in both directions. The field can be of any type that reacts in a meaningful way with a setStringValue/stringValue.

Dynamic scripting: MLABComboBoxControl

ComboBox [FIELD] {
  editable           = BOOL
  autoComplete       = BOOL
  maxCount           = INT
  insertPolicy       = ENUM
  duplicatesEnabled  = BOOL
  comboField         = FIELD
  comboSeparator     = STRING   // (default: ",")
  activatedCommand   = SCRIPT
  textChangedCommand = SCRIPT
  
  items {
    item {
      image = FILE
      title = STRING
    }
    ...
  }
}

editable = BOOL (default: Yes)

set if comboxbox string is editable.

autoComplete = BOOL (default: No)

set if combobox auto completes when editable.

textChangedCommand = SCRIPT(argument: string)

script that is executed when the text in the combo box changes (every time the user types something).

activatedCommand = SCRIPT (argument: string)

script that is executed when a combobox item is selected or entered by typing and pressing return.

maxCount = INT (default: not set)

maximum number of items.

insertPolicy = ENUM (Default:AtBottom)

where new items are inserted when combo box is editable.

Possible values: NoInsertion,AtTop,AtCurrent,AtBottom,AfterCurrent,BeforeCurrent

duplicatesEnabled = BOOL (default: Yes)

allow to enter duplicate items when editable (does not apply to script methods that insert items).

comboField = FIELD

a field whose string value is split and used instead of given items.

When the comboField changes, the available combo list is updated.

comboSeparator = STRING (default:",")

string value to use for splitting the string value of comboField into individual values.

items

specify the items shown in the ComboBox. May be omitted if comboField is given.

Each item is specified with the item tag.

Each item entry can hold the following tags:

image = FILE: image to be used for the item
title = STRING: title to be used for the item

Example 1.10. ComboBox

Have a look at the module TestComboBox. This module features a ComboBox and some scripting for adding new items dynamically, as well as clearing all items by scripting. The module also features the use of icons in a ComboBox.

Because the major portion of this example module is implemented in scripting, the code is not printed here.

1.3.4.8. MenuBar

MenuBar is a control that shows a menu bar with a number of pop-up menus. It can contain n SubMenu entries. See SubMenu for details on the menu definition.

Typically a MenuBar should only be used on the top of a window, but there is no layout restriction on that.

Dynamic scripting: MLABMenuBarControl

MenuBar {
  SubMenu NAME {
    ...
  }
  // more SubMenus ...
}

Example 1.11. MenuBar

Have a look at the module TestPopupMenu. This module shows how to setup various menues on a module's GUI. The first menu created on that module uses a MenuBar with only one entry.

1.3.4.9. ColorEdit

ColorEdit shows a colored box and allows to edit an RGB color. If the user double-clicks on the colored box, a ColorDialog pops up and you can pick a color. The given field has to be of type MLABColorField. The field is synchronized with the ColorEdit in both directions.

Dynamic scripting: MLABColorEditControl

	Tip
	You can also drag colors between color edits.

ColorEdit FIELD {
  mode = ENUM
}

mode = ENUM (default: Box): possible values are box and triangle, where box just shows a colored box and triangle shows a HSV color triangle for in-place editing

Example 1.12. ColorEdit

Have a look at the module TestVerticalLayout. This module features, amongst others, the use of a ColorEdit.

1.3.4.10. LineEdit

LineEdit shows a single line with an editable string. Typically it can be edited. If you want a non-editable text, use Label instead. LineEdit typically is synchronized bidirectionally with a given field, but it can also be used in scripting only.

Dynamic scripting: MLABLineEditControl

LineEdit [FIELD] {
  value                = STRING
  textAlignment        = ENUM
  minLength            = INT
  maxLength            = INT
  hintText             = STRING
  trim                 = ENUM
  returnPressedCommand = SCRIPT
  textChangedCommand   = SCRIPT
  lostFocusCommand     = SCRIPT
  validator            = REGEXP
  updateFieldWhileEditing = BOOL
}

value = STRING

value of the line edit if FIELD is omitted.

minLength = INT

minimum number of characters that should be visible in the LineEdit.

maxLength = INT

maximum allowed length of text.

hintText = STRING

Hint text shown in editable line edit if line edit is empty and doesn't have the focus.

updateFieldWhileEditing = BOOL (default: False)

Sets if the attached field is updated while the user types text in the line edit.

textAlignment = ENUM

how the text is aligned.

Possible values: Auto, Left, Right, Center

editMode = ENUM

Use for password editing.

Possible values: Normal (default), Password

trim = ENUM (default: None)

trims the string when it is not edited. Trimming only works if there is an attached field.

Possible values: Left, Center, Right, None

Left: "...LongText"

Center: "Long...Text"

Right : "LongText..."

None: No trimming

returnPressedCommand = SCRIPTtextChangedCommand = SCRIPT

scripting commands which are called when return is pressed or text has changed.

lostFocusCommand = SCRIPT

called when the focus is lost. Use the isModified method to check if the text was edited by the user

validator = REGEXP

a regular expression can be given to specify what kind of entries are valid.

Example 1.13. LineEdit

Have a look at the module TestVerticalLayout. This module features, amongst others, the use of a LineEdit.

1.3.4.11. NumberEdit

NumberEdit shows a edit box for integers, floats and doubles, which also has a step up/step down button (if step value is given). A field has to be given to which the NumberEdit is synchronized bidirectionaly. If the field has a min/max value, the edited value is automatically clamped to these values. If no format is given, floating point precision is 3.

Dynamic scripting: MLABNumberControl

NumberEdit FIELD {
  step      = FLOAT        // step
  stepstep  = FLOAT        // stepstep results in two additional step buttons with stepstep value
  format    = FORMATSTRING // format to be printed as in sprintf, e.g., %4.5f or %x
  minLength = INT          // minimum number of character that should be visible in the line edits
  editAlign = ENUM         // alignment of the text in the Line/NumberEdits (Left, Right(=default), Center))
}

step = FLOAT

step value for step buttons.

stepstep = FLOAT

extra step value for stepping bigger steps.

format = STRING

format to be printed as in sprintf, e.g., %4.5f or %x .

	Note
	you have to use the right %d,%x ,%f,%g type for float/double/int Fields

minLength = INT

Minimum number of character that should be visible in the LineEdit.

editAlign = ENUM (default: Right)

alignment of the text in the Line/NumberEdits.

Possible values: Left, Right, Center

wrap = BOOL

if set to 'Yes' and FIELD has min/max value, step and stepstep wrap the value around when reaching the boundaries.

Example 1.14. NumberEdit

Have a look at the module TestHorizontalLayout. This module features, amongst others, the use of a NumberEdit.

1.3.4.12. VectorEdit

The Apply button is only needed for the Rotation Field, because the Rotation Vector is always normalized immediately. It can be switched on for other fields if wanted.

Dynamic scripting: MLABVectorControl

VectorEdit {
  edit               = BOOL
  format             = STRING
  minLength          = INT
  editAlign          = ENUM
  applyButton        = BOOL
  sunkenVectorLabels = BOOL
  spacing            = INT
}

edit = BOOL (default: YES)

if vector is not editable, Labels are used instead of NumberEdits.

format = STRING

format to be printed as in sprintf, e.g., %4.5f or %x .

	Note
	You have to use the right %d,%x ,%f,%g type for float/double/int fields.

minLength = INT (default: 3)

Minimum number of character that should be visible in the NumberEdits.

editAlign = ENUM (default: Right)

alignment of the text in the NumberEdits.

Possible values: Left, Right, Center

applyButton = BOOL

is on for Rotation fields, otherwise the default is off. When turned on, you can edit all fields of a vector and apply it afterwards at once by pressing "Apply".

sunkenVectorLabels = BOOL (default: Yes)

if set to yes, draw Labels into the same Frame as the LineEdit, otherwise draw them separately

spacing = INT

set the internal spacing between the GUI elements of a VectorEdit.

Example 1.15. VectorEdit

Have a look at the module DRR. This module uses two VectorEdit controls in a Grid layout.

Figure 1.9. VectorEdit Example

1.3.4.13. Slider

Slider shows a slider control for integers, floats and doubles. It can be laid out vertically or horizontally. A field has to be given to which the Slider is synchronized bidirectionally. Min/max values are taken from the field and will be adjusted automatically when the field's min/max value changes.

Dynamic scripting: MLABSliderControl

Slider FIELD {
  pageStep     = FLOAT
  snap         = FLOAT
  autoPageStep = FLOAT
  direction    = ENUM
  format       = FORMATSTRING
  tickmarks    = BOOL
  scale        = ENUM
  tracking     = BOOL
  
  pressedIndicatorField = FIELD
}

pageStep = FLOAT

step that is used when the user clicks left or right of the slider.

snap = FLOAT

If set to a value != 0, the slider always snaps to a value which are multiples of this value starting at the sliders minimum.

pressedIndicatorField = FIELD

The Field has to be a BoolField. It is set to true if the user presses the slider button and to false if the user releases the slider button.

autoPageStep = FLOAT

give step as percentage 0..1 of min/max value, overwrites pageStep.

direction = ENUM (default: Horizontal)

layout direction of slider.

Possible values: Vertical, Horizontal

format = FORMATSTRING

specify the format of the tool tip in sprintf format.

tickmarks = BOOL (default: No)

enable tick marks.

scale = ENUM (default: Normal)

defines the scale of the slider.

Possible values: Normal, Log

tracking = BOOL (default: Yes )

sets if the slider updates the field while the slider is being dragged.

Example 1.16. Slider

Have a look at the module TestHorizontalLayout. This module shows the use of various controls for a float number.

1.3.4.14. IntervalSlider

IntervalSlider shows a double slider control for integers, floats and doubles. It can be laid out vertically or horizontally. A widthField and centerField pair or a lowerField and upperField pair has to be given to which the Slider is synchronized bidirectionally. Min/Max values are taken from the lower/upper fields or from the center field and will be automatically adjusted when field's min/max value changes.

When width/center is given, the slider acts in window/level mode so that the window can be of (max/min) size. When lower/upper is given, it allows choosing lower and upper values and is bound strictly to min/max values.

Dynamic scripting: MLABIntervalSliderControl

	Tip
	Only width/center or lower/upper field pairs can be given, NOT both!

IntervalSlider {
  step        = FLOAT
  snap        = FLOAT
  direction   = ENUM
  tracking    = BOOL
  centerField = FIELD
  widthField  = FIELD
  upperField  = FIELD
  lowerField  = FIELD
  
  pressedIndicatorField = FIELD
}

step = FLOAT

step that is used when the user clicks left or right of the slider.

snap = FLOAT

if set to a value != 0, the slider always snaps to a value which are multiples of this value starting at the sliders minimum.

pressedIndicatorField = FIELD

the Field has to be a BoolField. It is set to true if the user presses the slider button and to false if the user releases the slider button.

direction = ENUM (default: Horizontal)

layout direction of slider.

Possible values: Vertical, Horizontal

tracking = BOOL (default: Yes )

sets if the slider updates the field while the slider is being dragged.

centerField = FIELD

sets the center (alias level) field of the interval (min and max values are also taken from this field).

widthField = FIELD

sets the width (alias window) field of the interval.

lowerField = FIELD

sets the lower field of the interval (min value is also taken from this field).

upperField = FIELD

sets the upper field of the interval (max value is also taken from this field).

Example 1.17. IntervalSlider

Have a look at the module View3D. If the window 'View3D' (the default window) is opened, IntervalSliders are used on the 'Clipping' tab for adjusting the size of a subimage.

Figure 1.10. IntervalSlider Example

1.3.4.15. ThumbWheel

ThumbWheel shows a wheel that can be turned. When the wheel is turned, it changes the associated Field, which can be an Integer, Float, Double or Rotation field. The ThumbWheel adapts to the given min and max value of a field automatically. For Rotation fields (which have not min/max value), it automatically takes 0-359 degrees as min/max values. This can also be used for Float and Double fields by setting rotationMode to true. Otherwise the fields min/max values are used.

Dynamic scripting: MLABThumbWheelControl

ThumbWheel FIELD {
  snap         = FLOAT
  tracking     = BOOL
  wrapsAround  = BOOL
  direction    = ENUM
  ratio        = FLOAT
  rotationMode = BOOL
  
  pressedIndicatorField = FIELD
}

snap = FLOAT

the value of the wheel always snaps to a multiple of the snap value. If not given, an automatic value is calculated.

tracking = BOOL (default: Yes)

sets if the wheel updates the field while being dragged

pressedIndicatorField = FIELD

The Field has to be a BoolField. It is set to true while the used presses the mouse on the wheel.

direction = ENUM (default: Horizontal)

layout direction of slider.

Possible values: Vertical, Horizontal

ratio = FLOAT (default: 1)

defines the ratio between turning the wheel one whole turn and the min/max range.

wrapsAround = BOOL (default: No )

sets if the slider wraps around when min/max is reached.

rotationMode = BOOL (default: No )

turns wheel min/max values of a Float/Double field to 0-359 degrees (in radian), to allow easy setup for rotations.

Example 1.18. ThumbWheel

Have a look at the module DRR. There, ThumbWheels are used for adjusting the beam path rotation around the z- and x-axis.

Figure 1.11. ThumbWheel Example

1.3.4.16. TextView

TextView shows a text (which may be simple text or RichText). It can be editable or just a display, and is scrollable. It typically shows a title and an Apply button. If a field is given, the fields string value is shown. When a field is given, it is synchronized bidirectionally. Typically the user has to press the "Apply" button to set the text to the field. If autoApply is on, each change to the text changes the field's string value. The "Apply" button is only visible when edit is set to 'Yes'.

Dynamic scripting: MLABTextViewControl

TextView [FIELD] {
  title        = STRING
  text         = STRING
  edit         = BOOL
  autoApply    = BOOL
  hscroller    = ENUM
  vscroller    = ENUM
  textFormat   = ENUM
  console      = BOOL
  tabStopWidth = INT
  
  visibleRows     = INT
  showLineNumbers = BOOL
}

title = STRING

string to show as title (otherwise it is the name of the field).

text = STRING

string to show if field is not given.

edit = BOOL (default: Yes)

text is editable or display only.

autoApply = BOOL (default: No)

value is applied to field whenever it changes.

textFormat

sets the text format. The default is 'Auto', which searches the first text line for <> tags and switches between Rich and Plain. In Rich mode you can use html like syntax for the text.

Possible values: Auto, Rich, Plain

hscroller = ENUM (default: Auto)vscroller = ENUM (default: Auto)

select if a vertical/horizontal scrollbar is shown.

Possible values: Auto, On, Off

console = BOOL (Default: No)

scroll to end of buffer on each append or new field value.

tabStopWidth = INT (Default: 80 pixels)

sets the width of a tab stop in pixels.

wrap = ENUM (Default: Widget)

sets the wrap mode of the TextView. The default Widget' wraps at word boundaries inside the visible portion of the widget. "off" switches off wrapping, "column" wraps at a column specified by wrapColumn.

Possible values: Widget, Column, Off

wrapColumn = INT (Default: 80)

use this tag to set the column where to wrap words, when wrap is set to column. The tag should only be used when wrap is set to column.

visibleRows = INT

sets the minimum size of the TextView to hold at least n visible rows.

showLineNumbers = BOOL (default: No)

toggles the showing of line numbers. Only filled lines are numbered if switched on. Numbering starts with 1. Default is Off.

1.3.4.17. HyperText

HyperText shows a RichText which can be any size and which is scrollable when bigger than the available space. In contrast to TextView, the text is always read-only. The text can contain hyper links of various kinds, which can also have a tool tip on them. The shown text can be specified directly in the text tag, from a text file or from a field. If a field is used, the text is updated whenever the field changes.

Dynamic scripting: MLABHyperTextControl

Example of hyper links:

<a href="http://www.mevis.de">Mevis Home Page</a>
<a href="mailto:MeVisLab@mevis.de">MeVisLab Mail</a>
<a href="#someanchor">Link inside this document</a>
<a name="someanchor">Link anchor inside this document</a>
<a name="tooltip:Some tooltip" href=...>A link with additional tooltip</a>
<a href="usercmd:somecommand">A call to the command script with "somecommand" as argument</a>
<a href="js: MLAB.log('hello')">A link that directly executes JavaScript</a>
<a href="whatsthis:Some RichText">A link that shows a WhatsThis bubble that contains RichText</a>
For details, see the example module TestHyperText.

HyperText is derived from Frame.

HyperText {
  text      = RICHTEXT
  textField = FIELD
  textFile  = FILE
  command   = SCRIPT
  
  // Additional: tags from Frame
}

text = RICHTEXT

text that is shown. If you want to reference local files or images, use the $(LOCAL)/ variable to address these

textField = FIELD

text is taken from the string value of the field and is updated whenever the field changes

textFile = FILE

text is loaded from given file. Local links in the text are resolved local to that file, so you can link to other documents and images

command = SCRIPT (arg: string)

this command is called for each "usercmd:" hyper link when the link is clicked. The string after the "usercmd:" is passed to the command.

This tag allows to create dynamic scripts that are executed when a link is clicked. All clicks are mapped to the given command, in which you can do different things depending on the argument after the "usercmd:"

Example 1.19. HyperText

Have a look at the module TestHyperText. This module features a HyperText and documents some of the available options.

Figure 1.12. TestHyperText Module

1.3.4.18. HyperLabel

HyperLabel is identical to HyperText in its features, but shows the text as a label. Therefore it is not scrollable and automatically gets as big as the contained text. It behaves like a normal label but has the features of dynamic scripted links. Another advantage over a normal label is that the text can be selected and copied. For details see the HyperText control above. Note that title, titleField and titleFile are aliases for text, textField and textFile of HyperText. If the displayed text should be laid out in one line, then it has to be enclosed in "<nobr></nobr>".

HyperLabel is derived from Frame.

Dynamic scripting: MLABHyperLabelControl

HyperLabel {
  title      = RICHTEXT
  titleField = FIELD
  titleFile  = FILE
  command    = SCRIPT
  
  // Additional: tags from Frame
}

title = RICHTEXT: text that is shown. If you want to reference local files or images, use the $(LOCAL)/ variable to address these.
titleField = FIELD: text is taken from the string value of the field and is updated whenever the field changes.
titleFile = FILE: text is loaded from given file. Local links in the text are resolved local to that file, so you can link to other documents and images.

Example 1.20. HyperLabel

Have a look at the module TestHyperText. This module features a HyperLabel at the very top of its GUI.

1.3.4.19. ListBox

ListBox shows a list of single line items. The list can be set by scripting or from fields providing the items via splitting the string. The ListBox takes the string value of the values tag or of the given field and creates items out of these strings. If a field is given, updates the list from the field's string value changes. Scripting methods can be found in the MeVisLab Scripting reference.

Dynamic scripting: MLABListBoxControl

ListBox [FIELD] {
  values        = STRING
  visibleRows   = INT
  selectionMode = ENUM
  rowSeparator  = STRING
  
  selectionChangedCommand = SCRIPT
  selectedCommand         = SCRIPT
  currentChangedCommand   = SCRIPT
  doubleClickedCommand    = SCRIPT
  returnPressedCommand    = SCRIPT
  contextMenuOnEmptyList  = BOOL
  
  contextMenu {
    // See definition of SubMenu
  }
}

values = STRING

string that is used for the values instead of the FIELD.

rowSeparator = STRING (default "@")

separator string used for columns.

visibleRows = INT

set minimum height to show at least number of visible rows.

selectionMode = ENUM (default: Single)

defines if selection is possible and if multiple items can be selected at a time.

Possible values: Single, Extended, Multi, NoSelection

contextMenu

define a context menu to show on right-click the list. See SubMenu on how to define a menu.

contextMenuOnEmptyList = BOOL (default: Yes)

if set to 'No', do not show the user's contextMenu if the list has no entries.

selectionChangedCommand = SCRIPT

called when the selection has changed.

selectedCommand = SCRIPT (argument: index)

called when an item is selected (return is pressed or double-click the item).

currentChangedCommand = SCRIPT (argument: index)

called when the current item has changed.

doubleClickedCommand = SCRIPT (argument: index)

called when an item is double-clicked.

returnPressedCommand = SCRIPT (argument: index)

called when return is pressed on an item.

Example 1.21. ListBox

Have a look at the module TestListBox. This module features a dynamic setting and clearing of items, and it shows how to display items with icons.

Figure 1.13. TestListBox Module

1.3.4.20. ListView

ListView shows a list containing strings in rows/columns. The list can be set by scripting or from fields providing the items via splitting the string. The ListView takes the string value of the values tag or of the given field and creates items out of these strings. If a field is given, updates everything (even number of columns) from the field's string value changes. The first row in the string is taken as Header titles, further rows can contain less columns. The header titles have to be present even if the header visibility is turned off.

Limitations: Currently CheckBox items cannot contain RichText (see richText tag).

Dynamic scripting: MLABListViewControl and MLABScriptListViewItem

ListView [FIELD] {
  values          = STRING
  rowSeparator    = STRING
  columnSeparator = STRING
  layout          = STRING
  visibleRows     = INT
  cellSpacing     = INT
  selectionMode   = ENUM
  sortByColumn    = INT
  sortAscending   = BOOL
  header          = BOOL
  
  // advanced:
  richText        = BOOL
  toggleField     = FIELD
  checkList       = BOOL
  updateDelay     = UINT
  
  rootIsDecorated = BOOL
  
  contextMenuOnEmptyList = BOOL
  
  contextMenu {
    // See definition of SubMenu
  }
  
  // scripting:
  selectionChangedCommand = SCRIPT
  currentChangedCommand   = SCRIPT
  doubleClickedCommand    = SCRIPT
  returnPressedCommand    = SCRIPT
  clickedCommand          = SCRIPT
  
  // advanced scripting
  itemRenamedCommand          = SCRIPT
  itemCollapsedCommand        = SCRIPT
  itemExpandedCommand         = SCRIPT
  checkListItemChangedCommand = SCRIPT
  prepareEditCommand          = SCRIPT
}

values = STRING

string that is used for the values instead of the FIELD.

rowSeparator = STRING (default "\n")

separator string used for rows.

columnSeparator = STRING (default "@")

separator string used for columns.

layout = STRING

a string giving the layout of the columns "rlcet, rlcet, ..." (right left center edit toggle).

rlc - results in different alignment (right, left, center)

e - column is editable

t - one of the columns may have the "t" toggle flag, which means that a CheckBoxListItem is used and the toggleField updates checkbox states

visibleRows = INT

specifies a minimum size to fit number of visible rows (+ header) into the ListView.

cellSpacing = INT

adds extra spacing to all items.

selectionMode = ENUM (default: Single)

defines if selection is possible and if multiple items can be selected at a time.

Possible values: Single, Extended, Multi, NoSelection

sortByColumn = INT (default: -1)

select which column to sort by (default -1 means no sorting).

sortAscending = BOOL (default: Yes)

if 'No', sort in descending order.

header = BOOL (default: Yes)

selects if the header row is visible. If set to 'No', the header is not shown, while the titles still have to be provided via values or FIELD.

richText = BOOL (Default: No)

if set to 'Yes', the items in the list are used as RichText, allowing to change font type, size, colors etc.

See Section 1.3.9.2, “RichText” for details on RichText.

toggleField = FIELD

toggle state encoded in 0/1 chars (field is updated/updates in both directions).

checkList = BOOL (default: No)

if set to 'Yes', ListView uses CheckListItems. Normally this flag is not used; ListView is ToggleList, if toggleField is given.

updateDelay = UINT (default: 0)

defines the delay in milliseconds of the ListView update when the given FIELD is changed. If set to zero the update is immediate. This flag can be useful when the ListView is updated very often due to user interaction since it is slow to update. If you set e.g., a value of 100, the ListView will only update 10 times a second.

rootIsDecorated = BOOL (default: No)

this option toggles the display of icons to show if a node (item) is collapsed or expanded.

contextMenu

define a context menu to show on right-click the list, see SubMenu on how to define a menu.

contextMenuOnEmptyList = BOOL (default: Yes)

if set to 'No', do not show the user's contextMenu if the list has no entries.

selectionChangedCommand = SCRIPT

called when the selection has changed, if you want to get the selected item, call selectedItem() on the ListView.

currentChangedCommand = SCRIPT (argument: item)

called when the current item has changed.

doubleClickedCommand = SCRIPT (argument: item)

called when an item is double-clicked.

returnPressedCommand = SCRIPT (argument: item)

called when an item is renamed.

clickedCommand = SCRIPT (arguments: item, column)

called when an item is clicked (press+release of mouse button), column gives into which column the user clicked.

mouseButtonClickedCommand = SCRIPT(arguments: button, item, position, column)

This command is like clickedCommand, but provides more information. "button" is a number: 0 is the left mouse button and 1 is the right mouse button. "position" indicates the global mouse position, i.e., it is not relative to the list view.

itemRenamedCommand = SCRIPT (argument: item, column, newvalue)

called when an item is renamed.

itemCollapsedCommand = SCRIPT (argument: item)

called when an item with children is collapsed.

itemExpandedCommand = SCRIPT (argument: item)

called when an item with children is expanded.

checkListItemChangedCommand = SCRIPT (argument: item, column)

called when a check list item is toggled. The column parameter is important if you have created check boxes on other columns than the first with item.setCheckBoxOn().

prepareEditCommand = SCRIPT (argument: item, column)

called when a cell in the list view is about to be edited. This is mainly intended for use with the method setStringEditorValues() on the list view control, which allows one to provide a combo box instead of a simple line edit widget for editing of cells with string content.

Example 1.22. ListView

Have a look at the module TestListView. This module features the dynamic creation and removal of different list items.

Figure 1.14. TestListView Module

1.3.4.21. IconView

IconView shows a grid of icons with text. The items can be set by using the dynamic scripting API.

Dynamic scripting: MLABIconViewControl

IconView {
  allowRenaming = BOOL
  autoArrange   = BOOL
  wordWrap      = BOOL
  maxTextLength = INT
  maxItemWidth  = INT
  selectionMode = ENUM { values = "Single,Extended,Multi,NoSelection" }
  arrangement   = ENUM { values = "LeftToRight,TopToBottom" }
  resizeMode    = ENUM { values = "Fixed,Adjust" }
  itemTextPos   = ENUM { values = "Right,Bottom" }
  spacing       = INT
  
  selectionChangedCommand = SCRIPT
  currentChangedCommand   = SCRIPT
  selectedCommand         = SCRIPT
  doubleClickedCommand    = SCRIPT
  returnPressedCommand    = SCRIPT
  itemRenamedCommand      = SCRIPT
  contextMenuOnEmptyList  = BOOL
  
  contextMenu {
    // See definition of SubMenu
  }
}

allowRenaming = STRING (default: No)

allows in-place renaming of items.

autoArrange = BOOL (default: No)

rearranges items when new items are inserted.

resizeMode = ENUM (default: Fixed)

sets if the items should be arranged when the view is resized.

Possible values: Fixed, Adjust

wordWrap = BOOL (default: No)

sets if words are wrapped in the text.

maxTextLength = INT (default: 255)

sets the maximum number of displayed chars.

maxItemWidth = INT

sets the maximum width an item can have.

selectionMode = ENUM (default: Single)

defines if selection is possible and if multiple items can be selected at a time.

Possible values: Single, Extended, Multi, NoSelection

arrangement = ENUM (default: LeftToRight)

defines how items are arranged.

Possible values: LeftToRight, TopToBottom

itemTextPos = ENUM (default: Bottom)

sets the position of the text.

Possible values: Right, Bottom

spacing = INT

defines the spacing between items.

contextMenu

define a context menu to show on right-click the list. See SubMenu on how to define a menu.

contextMenuOnEmptyList = BOOL (default: Yes)

if set to 'No', do not show the user's contextMenu if the list has no entries.

selectionChangedCommand = SCRIPT

called when the selection has changed, if you want to get the selected item, call selectedItem() on the iconview.

selectedCommand = SCRIPT (argument: index)

called when a single item is selected (in Single selection mode).

currentChangedCommand = SCRIPT (argument: index)

called when the current item has changed.

doubleClickedCommand = SCRIPT (argument: index)

called when an item is double-clicked.

returnPressedCommand = SCRIPT (argument: index)

called when an item is renamed.

itemRenamedCommand = SCRIPT (argument: index, newvalue)

called when an item is renamed.

Example 1.23. IconView

Have a look at the module TestIconView. This module features the dynamic adding and removing of icon items, as well as a scripting example on how to react on clicking an icon.

Figure 1.15. TestIconView Module

1.3.5. Decoration GUI Controls

1.3.5.1. Label

Label shows a RichText label which can be multiline. The label content can be given as a text or by the string value of a field.

Label is derived from Frame.

Dynamic scripting: MLABLabelControl

          Label STRING {
          title         = STRING
          titleField    = FIELD
          image         = FILE
          indent        = INT
          buddy         = NAME
          textAlignment = ENUM
          textWrap      = ENUM
          textFormat    = ENUM
          trim          = ENUM
          expandTabs    = BOOL
          selectable    = BOOL
          allowLinks    = BOOL
          linkActivatedCommand = SCRIPT
          linkHoveredCommand   = SCRIPT
          // Additional: tags for Frame
          }

title = STRING

title given as text.

titleField = FIELD

title given as value of field (updated when field changes).

image = FILE

a pixmap to show on the label.

indent = INT

set number of pixels to indent text.

buddy = NAME

selects the name of another control that is used as "buddy" of the label, which gets input focus when the label gets the focus (e.g., by pressing an ALT key). Use the & char to set a keyboard shortcut.

textAlignment

Describes the alignment of the text in the Label.

Possible values: Auto, TopLeft, Top, TopCenter, TopRight, Left, Center, Right, BottomLeft, Bottom, BottomCenter, BottomRight

textWrap

Describes how the text in the Label is wrapped.

Possible values: SingleLine, WordBreak

textFormat

Sets the text format. The default is Auto, which searches the first text line for <> tags and switches between Rich and Plain. For keyboard shortcuts, write a & char in the plain text (&& means a literal &). In Rich mode you can use html-like syntax for the label.

Possible values: Auto, Rich, Plain

trim = ENUM (default: None)

trims the string.

Possible values: Left, Center, Right, None

Left: "...LongText"

Center: "Long...Text"

Right : "LongText..."

None: No trimming

expandTabs = BOOL

expands tab chars to the next tab stop.

selectable = BOOL (default: No)

allows to select text with the mouse.

allowLinks = BOOL (default: No)

allows to click on hyper links, enables linkHoveredCommand and linkActivatedCommand. If the linkActivatedCommand is not given, the links are opened via the external program given in MeVisLab preferences.

linkHoveredCommand = SCRIPT (arguments: String)

Command that is called when the user hovers over a link and allowLinks is set to true.

linkActivatedCommand = SCRIPT (arguments: String)

Command that is called when the user clicks on a link and allowLinks is set to true.

1.3.5.2. Image

Control that shows an image. The image can be automatically resized to fit the available space.

Image is derived from Frame.

Dynamic scripting: MLABImageControl

Image {
  image       = FILE
  scaleFactor = FLOAT
  autoResize  = BOOL
  
  // Additional: tags for Frame
}

image = FILE: image to be shown. The recommended image format is PNG.
scaleFactor = FLOAT (default: 1.0): scale factor of the image.
autoResize = BOOL (default: No): if set to 'Yes', the image is resized according to its aspect ratio to fit the available space.

1.3.5.3. Separator

Separator is a visual separator (like <HR> in html). It has a direction and a frame style. Depending on the direction, expandX and expandY are automatically set to expanding.

Separator is derived from Frame.

Dynamic scripting: MLABSeparatorControl

Separator {
  direction = ENUM
  
  // Additional: tags for Frame
}

direction = ENUM (default: Horizontal)

direction of the separator.

Possible values: Vertical, Horizontal

1.3.5.4. Empty

Empty is a control which represents empty space. Depending on its size policy, it will extend or be of fixed size. Its tags are derived from the basic control, typically one only uses the given tag.

There are four aliases that have useful presets in vertical and horizontal direction:

VSpacer, SpacerX - control that fills the space vertically by expanding (when you have a control with a stretch factor, you might want to change the stretch factor as well).

HSpacer, SpacerY - control that fills the space horizontally by expanding (when you have a control with a stretch factor, you might want to change the stretch factor as well).

Empty is derived from Control.

Empty {
  expandX  = ENUM
  expandY  = ENUM
  stretchX = INT
  stretchY = INT
  w        = INT
  h        = INT
}

1.3.5.5. ProgressBar

ProgressBar shows the current status as a bar between 0 and 100%. The status is given by a FloatField which should change values from 0 to 1.0. The field needs priority 0 to cause an update of the progress immediately, otherwise the update is not guaranteed.

ProgressBar is derived from Frame.

Dynamic scripting: MLABProgressBarControl

ProgressBar FIELD {
  textVisible = BOOL
  
  // Additional: tags for frame
}

textVisible = BOOL (default: Yes): This boolean tag holds whether the current completed percentage should be displayed.

Example 1.24. ProgressBar

Have a look at the module WEMIsoSurface. On this module, a ProgressBar is used to display the progress of scanning the slices of the input image.

Figure 1.16. ProgressBar Example

1.3.6. Menu GUI Controls

Menus can be created at various GUI controls, e.g., as a context menu. All these menus start at the level of a SubMenu as given in the following section.

Example 1.25. PopupMenu, SubMenu and MenuItem

For the use of the controls PopupMenu, SubMenu and MenuItem, have a look at the module TestPopupMenu.

Figure 1.17. TestPopupMenu Module

1.3.6.1. PopupMenu

A PopupMenu defines a menu that can be popped up via scripting. It is derived from the SubMenu control and is not visible by default. It should be given a name and then be shown via the popup() method. It pops up at the cursor position or at a screen point given by the caller.

Dynamic scripting: MLABPopupMenuControl

PopupMenu {
  name        = NAME
  showCommand = SCRIPT
  hideCommand = SCRIPT
  
  // possible children:
  Separator   = ""
  SubMenu     = NAME { ... }
  MenuItem    = NAME { ... }
  
  // advanced children:
  Action      = NAME
}

name = NAME: internal name used in scripting (like Control name/instanceName).
showCommand = SCRIPT
hideCommand = SCRIPT: script command when SubMenu is shown/hidden.

1.3.6.2. SubMenu

A SubMenu can contain multiple MenuItems, SubMenus, Separators and Actions. When an item is selected, a script command is called on the item. An ALT keyboard shortcut can be assigned with the "&" character.

Actions are an advanced concept and are currently only supported for the internal MeVisLab menus.

Dynamic scripting: MLABPopupMenuControl

SubMenu STRING {
  name        = NAME
  showCommand = SCRIPT
  hideCommand = SCRIPT
  
  itemActivatedCommend = SCRIPT
  
  // possible children:
  Separator = ""
  SubMenu   = NAME { ... }
  MenuItem  = NAME { ... }
  
  // advanced children:
  Action    = NAME
}

name = NAME: internal name used in scripting (like Control name/instanceName).
showCommand = SCRIPT
hideCommand = SCRIPT: script command when SubMenu is shown/hidden.
itemActivatedCommand = SCRIPT: script command that is called when a direct child of the SubMenu is activated.

1.3.6.2.1. MenuItem

MenuItems can be declared inside of a SubMenu or a tag used as a submenu (e.g., contextMenu, menuBar).

Dynamic scripting: MLABPopupMenuControl, using the name of the menu item.

MenuItem STRING {
  command   = SCRIPT
  name      = NAME
  field     = NAME
  enabled   = BOOL
  checked   = BOOL
  icon      = FILE
  accel     = KEYSEQUENCE
  whatsThis = STRING
  
  // advanced:
  slot      = QTSLOT
  receiver  = NAME
}

command = SCRIPT (arguments: name): script command that is executed when the item is selected.
name = NAME: a name that is given to this item that can be used in the interface of the SubMenu to talk to the item via scripting.
field = NAME: an existing field which can be of type bool or trigger. If this is used, selecting this menu item either toggles the boolean value or notifies the trigger field.
accel = KEYSEQUENCE: additional accelerator key sequence
enabled = BOOL (default: Yes): defines if the item is enabled (or disabled/grayed out otherwise)
whatsThis = STRING: additional whatsThis text
icon = FILE: additional icon that is shown
checked = BOOL(default: No): for toogle items, select the initial state
slot = QTSLOT: advanced feature, gives Qt slot instead of script command (used for MeVisLab internal menus)
receiver = NAME: advanced feature, gives names Qt object as receiver (used for MeVisLab internal menus)

1.3.6.2.2. Separator

Create a separator in the menu.

Separator = ""

1.3.7. Complex GUI Controls

1.3.7.1. Panel

Panel is a control that can "clone" a subregion of a given module's windows. If panel and panelByGroupTitle are not specified, the control shows the window of a module given by its name. If the window is not specified, the whole default window is shown.

This also clones all FieldListeners contained in the cloned code, so that a cloned panel should work like the original one. The window you get when you call window() in the context of the cloned script will be the window in which the Panel is.

Note that no field connections can be established between fields that are shown on a macro's GUI because of a panel declaration. In order to be able to establish a field connection to such a field, you need to declare the according field in the macro module's interface section

Panel is derived from Control.

Dynamic scripting: MLABPanelControl

	Tip
	When you use the Panel control, you should use the `panel` tag and use the `panelName` tag in the module to mark the region you want to clone. This allows the developer of the module to see that someone is using that part of the module panel somewhere else.

	Warning
	`panelByGroupTitle` is deprecated and should not be used in new scripts (see above tip).

Panel {
  module = NAME
  panel  = NAME
  window = NAME
  
  // tags that should not be used any more in new panels:
  panelByGroupTitle = NAME
}

module = NAME (required): name of the module in the network.
panel = NAME: search for a subpanel in the given module by looking for a panelName tag with the name NAME.
window = NAME: specify the name of the window to clone
panelByGroupTitle = NAME (deprecated!): search for the panel by comparing NAME with the values of all group tags in the module's window

Example 1.26. Panel

Have a look at the module View3D. As explained in the Window example, the View3D module defines four different windows. The first window (named 'View3D') defines a viewer and a settings panel. The latter has its panelName set to 'Settings'. The third window of the module (named 'Settings') just cuts out the settings part of the first window by using the Panel tag.

1.3.7.2. DynamicFrame

DynamicFrame shows a user-defined MDL script file. Its contents can be changed interactively from Python or JavaScript. This gives the user the power to create and update dynamically user interfaces in an application, without the need to specify the complete GUI when the application script is started.

The controls in the content of the frame (named with the name tag) are visible in the global scope of the window.

You can use the Python or JavaScript methods setContentFile(string) or setContentString(string).

Dynamic scripting: MLABDynamicFrameControl

	Tip
	If you dynamically add modules to your application network, you can use this control to clone a panel of the new module or to show fields of the new module on the fly.

DynamicFrame {
  autoSize    = BOOL
  contentFile = FILE
}

autoSize = BOOL (default: Yes): use the current sizes of the contained GUI.
contentFile = FILE: set the initially shown MDL file. If no file is specified, the DynamicFrame is empty.

1.3.7.3. Viewer

Viewer shows an OpenInventor Viewer. Typically the Inventor Viewer is taken from a SoViewerNode module in the network, especially SoExaminerViewer, SoRenderArea etc. A Viewer has to be attached to a SoNode field, typically the "self" field of an InventorModule. If you specify a type, the viewer is generated independent from a viewer node in the network.

Dynamic scripting: MLABInventorViewerControl

	Tip
	If you want to access the internal Inventor viewer, you should use the viewer together with an SoExaminerViewer or SoRenderArea on a network and use the self field of that module for the Viewer.

Viewer FIELD {
  viewing         = BOOL
  popup           = BOOL
  backgroundColor = COLOR
  type            = NAME
  clone           = BOOL
  border          = BOOL
  delay           = BOOL
  values          = STRING
  
  popupMenu {
    // see tags for SubMenu
  }
}

viewing = BOOL

set if viewer is in viewing mode.

popup = BOOL

set if viewer has pop-up menu.

backgroundColor = COLOR

set background color of viewer.

type = NAME

set type of the viewer if the SoNodeField is not from a SoViewerNode module.

Possible values: SoExaminerViewer, SoRenderArea, etc.

clone = BOOL (default: No): clone the viewer (this is automatically done when two viewers are show from the same module in the network).
border = BOOL: set if the viewer has a border.
delay = BOOL (default: Yes): set if the viewer is created in delayed mode, which means that its content is rendered AFTER the window is drawn the first time, to avoid waiting for the drawing of the rest of the GUI.
values = STRING: set field values of the viewer in Inventor style (you need to know what you are doing and what fields are available).
popupMenu: defines a menu that is shown when the user clicks the right mouse button on the viewer. The internal pop-up menu of the viewer (from OpenInventor) has to be turned off, otherwise this menu will not be shown. See SubMenu for details on how to define a menu.

Example 1.27. Viewer

Have a look at the module TestViewers. This module shows the use of the Viewer tag in different settings.

Figure 1.18. TestViewers Module

1.3.7.4. PathBrowser

PathBrowser displays a directory tree for browsing. Clicking a directory will open and show its subdirectories. Double-clicking a directory selects a directory. Typically this is used together with the DicomBrowser.

Pressing "r" on a PathBrowser always resets the current path to the original root path.

PathBrowser is derived from Control.

Dynamic scripting: MLABPathBrowserControl

PathBrowser {
  root        = PATH
  visibleRows = INT    // Minimum number of visible rows
  minLength   = INT    // Minimum width in number of the widest character of the current font
  sortBy      = STRING // Sort dirs by on of name, size, time, unsorted
  cd          = STRING // Relative path from ROOTPATH to initially opened subdir
  
  pathSelectedCommand   = SCRIPT
  pathDblClickedCommand = SCRIPT
}

root = PATH

sets the root path of the PathBrowser. If not given or if PATH does not exist or is not readable, the current working directory is used.

visibleRows = INT

minimum number of visible rows (defining the minimum height).

minLength = INT

minimum width to show INT characters.

sortBy = ENUM (default: Name)

sort directories by the given value.

Possible values: Name, Size, Time, Unsorted

cd = PATH

relative path from root to initially opened subdir.

pathSelectedCommand = SCRIPT (argument: absolute path)pathDblClickedCommand = SCRIPT (argument: absolute path)

script executed when path is selected/double-clicked with left mouse button.

1.3.7.5. DicomBrowser and DicomBrowserTable

The DicomBrowser displays a configurable tree view on a set of Dicom files. The data is arranged according to the Dicom hierarchy of the files. The DicomBrowser allows copying, moving and linking (only on Unix, yet) of Dicom data by dragging between DicomBrowsers. Dropping an entry from a DicomBrowser to a PathBrowser sets the Path of the PathBrowser to the directory of the dropped entry. Deleting selected datasets is also supported by pressing DEL.

A DicomBrowserTable that is connected to a DicomBrowser always shows a table view of the dataset currently selected in the DicomBrowser. The DicomBrowser and the DicomBrowserTable are synchronized in both directions. Double-clicking a dataset selects it for opening by other controls.

Pressing "r" on these controls reloads the currently viewed datasets, thus allowing the DicomBrowser to be synchronized with external modified directories.

DicomBrowser and DicomBrowserTable are derived from Control.

Dynamic scripting: MLABDicomBrowserControl and MLABDicomBrowserTableControl

DicomBrowser {
  name           = STRING   // The name of this control
  visibleRows    = INT      // Minimum number of visible rows
  minLength      = INT      // Minimum width in number of the widest character of the current font
  project        = STRING   // Name of a DicomProject to be loaded (default: none)
  hierarchy      = STRING   // Name of Dicom-Hierarchy (default: first one available)
  rootDir        = STRING   // Root-directory of Dicom-files (default: "")
  treeRootTitle  = STRING   // Set the title of the Tree-Views Root-Node, which is empty by default
  fileExtension  = STRING   // Parse only files with this extension (default: "dcm")
  includeFilter  = STRING   // Include these files in the search (default: "")
  excludeFilter  = STRING   // Exclude these files from the search (default: "")
  recursive      = BOOL     // If 'Yes', search files recursively (default: Yes)
  showDicomFiles = BOOL     // If 'No', does not show leafs of a DicomHierarchy in the Browser (default: Yes)
  
  selectedCommand          = SCRIPT // Script to evaluate when a dataset is selected
  deletionRequestedCommand = SCRIPT // Script to evaluate when a dataset should be deleted
  dblClickedCommand        = SCRIPT // Script to evaluate when a dataset is double-clicked
}
DicomBrowserTable {
  name                   = STRING // The name of this control
  visibleRows            = INT    // Minimum number of visible rows
  minLength              = INT    // Minimum width in number of the widest character of the current font
  contextMenuOnEmptyList = BOOL
  
  contextMenu {
    // See definition of SubMenu
  }
}
Execute = "*js: ctx.control("myDicomBrowser").setTableView(ctx.control("myDicomBrowserTable")); *"

visibleRows = INT: minimum number of visible rows (defining the minimum height).
minLength = INT: minimum width to show INT characters.
project = STRING: name of a DicomProject with presets for the DicomBrowser.
hierarchy = STRING: the name of a Dicom hierarchy which is displayed by the DicomBrowser.
rootDir = PATH: path to DicomFiles. Setting a PathBrowser overwrites this value.
treeRootTitle = STRING: Set the Title of the tree view root node, which is empty by default.
fileExtension = STRING: sets the filter of the file search to files with this extension.
includeFilter = STRING: include these files in the search.
excludeFilter = STRING: exclude these files from the search.
recursive = BOOL: if set to 'Yes', files are searched recursive.
showDicomFiles = BOOL (default: Yes): if set to 'No', no leafs of a Dicom hierarchy in the Browser are shown.
contextMenu: define a context menu to show on right-click the list. See SubMenu on how to define a menu.
contextMenuOnEmptyList = BOOL (default: Yes): if set to 'No', it is not shown that the user's contextMenu list has no entries.
selectedCommand = SCRIPT (argument: absolute path of dataset): Script to evaluate when a dataset is selected.
deletionRequestedCommand = SCRIPT (argument: absolute path of dataset): Script to evaluate when a dataset should be deleted.
dblClickedCommand = SCRIPT (argument: absolute path of dataset): Script to evaluate when a dataset is double-clicked.

1.3.7.6. MoviePlayer

The MoviePlayer allows to play AVI movies. The movie can be given as a filename and the control can be controlled interactively by Python or JavaScript.

MoviePlayer is derived from Control.

Dynamic scripting: MLABMoviePlayerControl

MoviePlayer {
  filename          = FILE
  autoStart         = BOOL
  enableContextMenu = BOOL
  showControls      = BOOL
}

filename = FILE: filename of the movie (should be an AVI).
autoStart =BOOL (default: No): sets if movie should start immediately.
enableContextMenu = BOOL (default: Yes): enable a context menu with advanced control functions.
showControls = BOOL (default: Yes): show play/stop etc. controls to the user.

1.3.7.7. ScreenshotGallery

The ScreenshotGallery can be used in an application to collect screenshots for that application. It can be used via scripting to get a list of taken screenshots and movies and to control to which directory these files are written etc.

ScreenshotGallery is derived from Control.

Dynamic scripting: MLABScreenshotGalleryControl

ScreenshotGallery {
  application = NAME
}

application = NAME: give a name of the application (macro module) whose screenshots should be stored.

1.3.7.8. WebView

The MDL WebView provides a complete web engine to the MDL developer. It is based on the open-source WebKit engine, which as well powers Apple's Safari and Google Chrome.

It offers:

A standards compliant web browser

JavaScript 1.5, CSS2, CSS3 and HTML5 Scripting interface to control the browser content, text selection, menu, ...

Scripting interface to call browser JavaScript from MeVisLab Python/JavaScript

Scripting of MeVisLab objects from within JavaScript (e.g., MLAB, ctx, ...)

Support for NSAPI conformant browser plugins (e.g., Flash, Silverlight, ...), typically plugins installed for Firefox plugins will just work

Support for embedded MDL controls inside of HTML documents

WebInspector for debugging HTML, CSS and JavaScript (Inspect option on context menu)

The WebView has a rich scripting API, which you can find in the MeVisLab Scripting Reference (look for MLABWebViewControl).

The WebView has special support for local URLs that are relative to MeVisLab Packages. You can write a URL relative to a MeVisLab Package by writing href="/MLAB_PackageGroup_PackageName/...", e.g., href = "/MLAB_MeVisLab_Standard/Modules/Macros/Tests/GUI/TestWebView/Intro.html".

For detailed examples, have a look at the TestWebView module, which shows most of the possibilities of the WebView.

WebView is derived from Control.

Dynamic scripting: MLABWebViewControl

WebView {
  contentUrl              = URL
  contentFile             = FILE
  contentString           = STRING
  contentStringBaseUrl    = URL

  loadStartedCommand      = SCRIPT
  loadProgressCommand     = SCRIPT
  loadFinishedCommand     = SCRIPT
        
  enableScriptingObjects  = BOOL
  enableEmbeddedMDL       = BOOL
  enablePlugins           = BOOL
        
  javaScriptInitCommand   = SCRIPT
  linkClickedCommand      = SCRIPT
  selectionChangedCommand = SCRIPT
  
  linkDelegation = ENUM    // { values = "None,External,All" }

contentUrl = URL: sets the content of the WebView to the given Url, e.g., http://www.mevislab.de

contentFile = FILE: sets the content of the WebView to the given local file, e.g., $(LOCAL)/SomeFile.html

contentString = STRING: sets the content of the WebView to the given HTML string. If no contentStringBaseUrl is given, the $(LOCAL) MDL variable is used as baseUrl for the string, so relative links are resolved relative to $(LOCAL).

contentStringBaseUrl = URL: allows to set a different base Url when using contentString.

loadStartedCommand = SCRIPT: is called when the WebView starts loading a document.

loadProgressCommand = SCRIPT (argument: float progress): is called with values from 0. to 1. while the WebView loads the document.

loadFinishedCommand = SCRIPT (argument: bool success): is called when the document has finished loading.

enableScriptingObjects = BOOL (default: No): this adds the ctx, MLAB, MLABFileManager, ... MeVisLab objects to the JavaScript engine of the WebView, so that they can be used to script MeVisLab from within the WebView JavaScripting.

enableEmbeddedMDL = BOOL (default: No)

enabling this allows to embedd MDL control inside of HTML pages using the HTML object tag. Have a look at the TestWebView module for an example of embedded MDL.

The window/panel/module parameters are optional. If no module is given, the current module associated with the MDL file is used. If no window is given, the default window is used. If a panel is given, MeVisLab searches for an MDL section with panelName equal to the given panel name.

<object type="text/mevislab-mdl" >
<param name="window" value="nameOfSomeMDLWindow"> </param>
<param name="panel"  value="nameOfSomePanel">     </param>
<param name="module" value="instanceNameOfModule"></param>
</object>

enablePlugins = BOOL (default: No): this enables NSAPI plugin support, you need to enable this so that Flash/Silverlight can be used inside of HTML pages.

javaScriptInitCommand = SCRIPT: this is called when a the JavaScript engine of a HTML page is reinitialized and can be used to add objects to the engine.

linkClickedCommand = SCRIPT (arguments: QUrl): this command is called for all clicked links that are delegated via the linkDelegation tag.

selectionChangedCommand = SCRIPT: This command is called whenever the text selection in the WebView changes.

linkDelegation = ENUM (possible values = "None,External,All" default: External)

the linkDelegation defines how clicks on links are handled. All links that are delegated are passed to the linkClickedCommand instead of switching the WebView to the Url internally. By default, all external links (which are not file:// links) are delegated. If the linkClickedCommand is not implemented, the delegated urls are passed to MeVisLab, which uses the default programs registered for the scheme of the url to open the url.

None: no links are delegated

External: external links (which do not point to the local disk using file://) are delegated

All: all links that are clicked are delegated

1.3.8. Event Handling Controls

1.3.8.1. Accel

Accel allows to add keyboard shortcuts that trigger fields or execute a Python or JavaScript command when pressed. They are local to the window they are declared in, thus they are only triggered when their parent window is active.

Accel can appear inside of all Group GUI controls. The field and command tags are both optional. Note that Accel should be stated before the other GUI controls for which the defined shortcuts should be available. I.e., if a certain shortcut should be available for a whole window, state the according Accel statement right at the beginning, just after the Window statement.

Dynamic scripting: MLABAccelControl

Accel {
  key     = KEYSEQUENCE
  field   = FIELD
  command = SCRIPT
}

key = KEYSEQUENCE: Shortcut that triggers the accelerator, e.g., CTRL+X, ALT+Z, CTRL+SHIFT+U.
field = FIELD: a trigger field that is touched when the keyboard shortcut is pressed.

command = SCRIPT: command that is called when the keyboard shortcut is pressed.

1.3.8.2. EventFilter

The EventFilter is an invisible GUI control that can be placed anywhere in the GUI. It allows to listen to the events that other controls (and optionally their children) receive and can then either prevent the event from being delivered or just pass through the event. It is a very powerful control since it allows to react on GUI events on a low level. You can e.g., use it to teach other controls drag-and-drop features, to notice when a window gets visible/hidden or when a control gets entered with the mouse and much more.

Dynamic scripting: MLABEventFilterControl

EventFilter {
  name     = NAME
  command  = SCRIPT
  filter   = NAMELIST
  eatEvent = BOOL
  children = BOOL
  debug    = BOOL
  control  = NAME
  ...
}

name = NAME: name of the EventFilter, for usage with ctx.control() method.
command = SCRIPT (argument: event as map, see below): the scripting method that is called for each event that matched the filter.
filter = NAMELIST: a list of event names that should be filtered.
eatEvent = BOOL (default: No): sets if the filtered events are eaten automatically (=not delivered).
children = BOOL (default: No): sets if the filter is applied to all subwidgets or just to the given controls.
debug = BOOL (default: No): prints all events to the console (just to see which events happen and which you might be interested in).
control = NAME: name of a control to filter events on, this tag can appear multiple times so that the filter listens to multiple controls at a time.

The filter can contain a number of Event names. These names are take from Qt. You can find the event details at http://doc.qt.nokia.com/4.6/qevent.html.

All events share the type property, which can be checked if multiple events are filtered. To print all properties of an event, use the JavaScript:

for (i in event) MLAB.log(i + ":" + event[i])

The most useful events are:

MouseButtonPress, MouseButtonRelease, MouseButtonDblClick, MouseMove

react on mouse button press or release and movement.

Event properties: x, y, globalX, globalY, button (one of "left","mid","right"), ctrlKey, shiftKey, altKey

Show, Hide

react on a control being shown or hidden.

Event properties: none (except type)

Enter, Leave

react on mouse entering or leaving the control area.

Event properties: none (except type)

DragEnter, DragMove, Drop

handle drag-and-drop on a low level.

Event properties: x, y, globalX, globalY

Wheel

handle the mouse wheel event.

Event properties: x, y, globalX, globalY, delta, orientation (one of "vertical","horizontal"), ctrlKey, shiftKey, altKey

Resize

handle resize event.

Event properties: width, height, oldWidth, oldHeight

KeyPress, KeyRelease

handle the key press event, where "ascii" is the ascii char, the text is unicode and the key can be used to access special keys, e.g., "Left", "Right" for cursor keys. See the Qt Key defines or have a look at the example in TestEventFilter.

Event properties: ascii, text, key, ctrlKey, shiftKey, altKey

Example 1.28. EventFilter

Have a look at the module TestEventFilter. This module features the reacting of certain areas of the GUI on defined mouse actions (button pressed, entered/leave, etc.) and the implementation of dragging and dropping of files or images.

Figure 1.19. TestEventFilter Module

1.3.9. Concepts

This chapter explains concepts that are used in many GUI controls, e.g., the layout engine, rich text etc.

1.3.9.1. Align Groups

By default, various GUI Controls are laid out depending on each other, e.g., Field controls in a Vertical automatically get the same label size, etc. This behavior can explicitly be specified by the concept of "Align Groups". A group is specified by its unique name, which you have to choose. All controls which are in the same group are aligned in respect to the type of the group.

There are three type of groups (given by their tag names):

alignGroupX (alias: alignGroup) - all child widgets of the control get the maximum width of all child widgets in that column.

alignGroupY - all child widgets of the controls get the maximum height of all child widgets in that row.

labelAlignGroup - all controls get the same maximum label size.

In simpler words: if two controls, e.g., Fields in the same Vertical, have the same alignGroup tag, all the subwidgets in the Field controls are aligned well in their widths.

The labelAlignGroup can be used to just align the labels, so that the other children of a Control will not be aligned. Have a look at the TestLayouter MacroModule in MeVisLab, which shows the differences.

	Important
Please note that the term "alignment" in this section might be misleading. In this context, alignment means getting the same width or height as another control. This does not necessarily mean a visual alignment, since the controls may be located at completely different positions. Also note that the alignment is a one-time process when the window is created, so it might get unaligned if you allow expanding of the controls via expandX, expandY.

Important

Please note that the term "alignment" in this section might be misleading. In this context, alignment means getting the same width or height as another control. This does not necessarily mean a visual alignment, since the controls may be located at completely different positions. Also note that the alignment is a one-time process when the window is created, so it might get unaligned if you allow expanding of the controls via expandX, expandY.

In addition to the above tags, which are used directly inside of a control that should be aligned, you can also use the childAlignGroupX (alias childAlignGroup) and childAlignGroupY tags, which can be specified in any control that has children. This causes all "simple" controls inside this control to get the specified align group. So you can just see it as a helper tag that helps you write less tags:

Vertical {
  childAlignGroup = group1
  Box {
    Field test1 { }
    Field test2 { }
  }
  Box {
    Field test3 { }
    Field test4 { }
  }
}

This is identical to the following, note that the boxes do not get the aligngroup and that the childAlignGroup tag works recursively.

Vertical {
  Box {
    Field test1 { alignGroup = group1 }
    Field test2 { alignGroup = group1 }
  }
  Box {
    Field test3 { alignGroup = group1 }
    Field test4 { alignGroup = group1 }
  }
}

The labelAlignGroup tag can also be used at a higher level and it causes all "simple" controls to get their labels aligned. See the TestLayouter MacroModule in MeVisLab for an example of the above tags.

1.3.9.2. RichText

The following tabels give you an overview of which tags are available in RichText. The RichText can be used in tooltips, whatsthis boxes, Label, HyperText, HyperLabel and various other places. The syntax is a simple subset of HTML, including lists, tables, images and links. Have a look at the TestHyperText module in MeVisLab to see some examples.

Table tags	Notes
`<table>...</table>`	A table. Tables support the following attributes: `bgcolor` -- The background color. `width` -- The table width. This is either an absolute pixel width or a relative percentage of the table's width, for example `width=80%`. `border` -- The width of the table border. The default is 0 (= no border). `cellspacing` -- Additional space around the table cells. The default is 2. `cellpadding` -- Additional space around the contents of table cells. The default is 1.
`<tr>...</tr>`	A table row. This is only valid within a table. Rows support the following attribute: `bgcolor` -- The background color.
`<th>...</th>`	A table header cell. Similar to `td`, but defaults to center alignment and a bold font.
`<td>...</td>`	A table data cell. This is only valid within a table row. Cells support the following attributes: `bgcolor` -- The background color. `width` -- The cell width. This is either an absolute pixel width or a relative percentage of table's width, for example `width=50%`. `colspan` -- Specifies how many columns this cell spans. The default is 1. `rowspan` -- Specifies how many rows this cell spans. The default is 1. `align` -- Alignment; possible values are `left`, `right`, and `center`. The default is `left`. `valign` -- Vertical alignment; possible values are `Top`, `Middle` and `Bottom`. The default is `Middle`.

Special tags	Notes
`<img>`	An image. The image name for the mime source factory is given in the source attribute, for example `<img src="qt.xpm">`. The image tag also understands the attributes width and height that determine the size of the image. If the pixmap does not fit the specified size it will be scaled automatically The align attribute determines where the image is placed. By default, an image is placed inline just like a normal character. Specify left or right to place the image at the respective side.
`<hr>`	A horizontal line.
`<br>`	A line break.
`<nobr>...</nobr>`	No break. Prevents word wrap.

Style tags	Notes
`<em>...</em>`	Emphasized. By default this is the same as `<i>...</i>` (italic).
`<strong>...</strong>`	Strong. By default this is the same as `<b>...</b>` (bold).
`<i>...</i>`	Italic font style.
`<b>...</b>`	Bold font style.
`<u>...</u>`	Underlined font style.
`<s>...</s>`	Strike out font style.
`<big>...</big>`	A larger font size.
`<small>...</small>`	A smaller font size.
`<code>...</code>`	Indicates code. By default this is the same as `<tt>...</tt>` (typewriter). For larger chunks of code, use the block-tag `<pre>`.
`<tt>...</tt>`	Typewriter font style.
`<font>...</font>`	Customize the font size, family and text color. The tag can have the following attributes: `color` -- The text color, for example `color="red"` or `color="#FF0000"`. `size` -- The logical size of the font. Logical sizes 1 to 7 are supported. The value may either be absolute (for example, `size=3`) or relative (`size=-2`). In the latter case the sizes are simply added. `face` -- The family of the font, for example `face="times"`.

Anchor tags	Notes
`<a>...</a>`	An anchor or link. A link is created by using an href attribute, for example `<a href="target.qml">Link Text</a>`. Links to targets within a document are written in the same way as for HTML, e.g., `<a href="target.qml#subtitle">Link Text</a>`. A target is created by using a name attribute, for example `9<a name="subtitle"><h2>Sub Title</h2></a>`.

Structuring tags	Notes
`<qt>...</qt>`	A Qt rich text document. It can have the following attributes: `title` -- The caption of the document. `type` -- The type of the document. The default type is `"page"`. It indicates that the document is displayed in a page of its own. Another style is `"detail"`, which can be used to explain certain expressions in more detail in a few sentences. Note that links will not work in documents with `<qt type="detail">...</qt>`. `bgcolor` -- The background color, for example `bgcolor="yellow"` or `bgcolor="#0000FF"`. `background` -- The background pixmap, for example `background="granite.xpm"`. The pixmap name needs to have an absolute path e.g., use `$(LOCAL)/image.png`. `text` -- The default text color, for example `text="red"`. `link` -- The link color, for example `link="green"`.
`<h1>...</h1>`	A top-level heading.
`<h2>...</h2>`	A sublevel heading.
`<h3>...</h3>`	A sub-sublevel heading.
`<p>...</p>`	A left-aligned paragraph. Adjust the alignment with the align attribute. Possible values are `left`, `right` and `center`.
`<center>...</center>`	A centered paragraph.
`<blockquote>...</blockquote>`	An indented paragraph that is useful for quotes.
`<ul>...</ul>`	An unordered list. You can also pass a type argument to define the bullet style. The default is `type="disc"`; other types are `circle` and `square`.
`<ol>...</ol>`	An ordered list. You can also pass a type argument to define the enumeration label style. The default is `type="1"`; other types are `"a"` and `"A"`.
`<li>...</li>`	A list item. This tag can be used only within the context of `<ol>` or `<ul>`.
`<pre>...</pre>`	For larger chunks of code. Whitespaces in the contents are preserved. For small bits of code, use the inline-style code.

1.3.9.3. Module Genre Definition

A module in MeVisLab can be in part of multiple genres, which are given with the genre tag. The available genres are given in MeVisLab/Standard/Modules/IDE/Genre.def and can also be extended via user genres.

	Note
	The names of the genres are defined by the value behind the Genre tag. These genre names may not contain spaces or special characters and are used in the genre tag in the modules' defintion. If you want a more specific title, you can use the title tag inside of a Genre to define the user-visible string.

Extract of Genre.def:

GlobalGenres  {
   Genre FileMain {
      title = File
      Genre = DICOM
      
      Genre InventorFile {
         title = Inventor
      }
      Genre File {
         title = Misc
      }
   }
   
   Separator = ""
   
   Genre ImageMain {
      title = Image
      Genre = Info
      Genre = Scale
      Genre = Generators
      
      Genre Image {
         title = Misc
      }
   }
   ...
}

Example of a module having two genres:

MLModule MyModule {
  genre = DICOM,Scale
}

If you are a MeVisLab core developer at MeVis, you can add genres in the Genre.def file.

If you are an external developer and you still need your own genres, you can add a UserGenres section to your *.def file (on the top level):

UserGenres {
  Genre SomebodysGenreMain {
    title = "A longer title for the genre"
    Genre SomebodysGenre {
    }
  }
  Genre +Diffusion {
    Genre DiffExtra {
    }
  }
}

As you can see above there are two notations:

1. Adding a new root genre by just giving a Genre tag with the name of the new genre.

2. Extending a known genre with new entries by writing a + and an existing genre name (defined in Genre.def).

Example: Genre +ImageMain { Genre = SomeNewSubGenre }

	Note
	UserGenres and GlobalGenres are only reloaded when MeVisLab is restarted or the whole database is reloaded.

1.3.9.4. ModuleGroup Definition

A module in MeVisLab can be given the membership in one or several ModuleGroups via the group tag. A ModuleGroup consists of the group tag id and extra semantic information about this id given via the ModuleGroup tag. The id has to be a single word and should start with your license prefix to avoid mixing groups up. The existing groups can be enabled/disabled in the Preferences Panel of MeVisLab.

There are a number of predefined groups which are used throughout MeVisLab:

- deprecated = a modules that is officially gone, only still there to make old stuff work.

- test = a module that tests MeVisLab features.

- example = a module that shows things as an example.

- internal = internal MeVisLab modules which are not visible to the public.

To put your module into a defined group write the following:

MLModule SomeModule {
  group = MyOwnGroup
}

Now we need extra information on the ModuleGroup to make it appear nicely in the Preferences Panel of MeVisLab.

ModuleGroup GROUPNAME {
  owner   = STRING
  title   = STRING
  comment = STRING
  type    = [internal | std]
  shy     = BOOL
}

If you are a MeVisLab core developer at MeVis, you can add your ModuleGroups directly to MeVisLab/Standard/Modules/IDE/ModuleGroups.def.

If you are an external developer, just put the additional ModuleGroups into any *.def file in you UserModulePath, they are read automatically.

1.3.9.5. Preloading DLLs

Shared Libraries (DLLs) are loaded by MeVisLab when they are needed by a module in a network (see the DLL tag of Section 1.2.1.6, “MLModule”). The PreloadDLL tag can be used to force MeVisLab to load a given DLL on startup. This can be useful when your own ML Type Extensions should be loaded on startup of MeVisLab.

The PreloadDLL tag can appear in any *.def file (on the top-level, not nested in other tags):

PreloadDLL DLLNAME {}
// or
PreloadDLL = DLLNAME

The DLLNAME is given without file extension. On Windows, ".dll" is appended in MeVisLab Release and "_d.dll" in MeVisLab Debug application. Mac OS X uses "libDLLNAME.dylib" to access the shared library. On Linux, "libDLLNAME.so" is used.

1.3.9.6. Styles

Styles can be defined globally but also locally in a user interface to change the GUI appearance. Every control supports the style tag, where you can give a style by its name (declared with DefineStyle) or by just opening a local style and deriving from the current style.

Example: See TestStyles macro module in MeVisLab.

Figure 1.20. TestStyles Module

1.3.9.6.1. DefineStyle

DefineStyle allows to define a new GUI style, either complete or just extending an existing style. The style provided with MeVisLab is called "default". Old ILAB4 styles are also supported, being defaultVerySmall, defaultSmall, defaultBig, defaultHuge. These styles should no longer be used and are replaced by the scale tag, with which you can resize all fonts in a GUI control by just giving the scale tag and a positive or negative integer for bigger/smaller fonts and spacings.

Styles can be used to change the whole user interface appearance or just to change a single color/font in a given control. See below for an example on how to do that.

A style contains Fonts, Colors and Prototypes. You can specify a different font for each of the following roles:

Titles (titleFont tag)
Editable text (editFont tag)
TabBar text (tabFont tag)
Box group titles (boxFont tag)

There are two different sets of colors, the default colors and the disabledColors specifies which colors a control uses when it is drawn. The disabledColors are used when a control is not enabled (also called "grayed out").

DefineStyle NAME {
   derive = NAME
   
   // font for titles in the GUI (Buttons, Labels, ...)
   titleFont {
     family     = NAME
     size       = INT
     weight     = ENUM
     italic     = BOOL
     fixedPitch = BOOL
   }
   
   // font for editing components in the GUI (NumberEdit, TextView, ...)
   editFont {
     // see titleFont
   }
   
   // font for TabViews
   tabFont {
     // see titleFont
   }
   
   // font for Box group titles
   boxFont {
     // see titleFont
   }
   
   colors {
     fg              = COLOR
     bg              = COLOR
     button          = COLOR
     buttonText      = COLOR
     editText        = COLOR
     editBg          = COLOR
     light           = COLOR
     midlight        = COLOR
     dark            = COLOR
     mid             = COLOR
     shadow          = COLOR
     highlight       = COLOR
     highlightedText = COLOR
     brightText      = COLOR
     link            = COLOR
     linkVisited     = COLOR
     boxText         = COLOR
     tabText         = COLOR
   }
   disabledColors {
     // same as above colors
   }
}

derive = NAME

select a style to derive from, all attributes are copied and you may overwrite any of the tags, e.g., just the font sizes, an individual colors etc.

titleFont, editFont, boxFont, tabFont

defines properties of a font (you do not need to specify all tags, reasonable defaults are taken from the underlying system settings.

family = NAME

specify a font family name; possible names are: Helvetica, Courier, ...

size = INT

set the point size of the font.

weight = ENUM

set the weight of the font.

Possible values: Light, Normal, DemiBold, Bold, Black

italic = BOOL

set if font should be italic.

fixedPitch = BOOL

set if the font should be fixed pitch (depends on font family).

colors, disabledColors

define the normal colors and the disabled colors for all controls in this style.

The syntax for COLOR in the style is:

colorname[:imagefilename]

where colorname can be one of:

#rrggbb
X11 color name (also on Windows)
name specified in Colors section

and imagefilename can be an extra image used as brush for that color. Using images is especially interesting for the background colors bg, editBg and button.

Examples:

bg = black:$(LOCAL)/someBackgroundImage.png

editBg = white

fg = COLOR: foregound text color used in Labels etc.
bg = COLOR: background color.
button = COLOR: background color of buttons.
buttonText = COLOR: text color on buttons.
editText = COLOReditBg = COLOR: color for editable text and background for text edits.
light = COLOR midlight = COLOR dark = COLOR mid = COLOR shadow = COLOR: colors used for drawing sunken and raised panels and buttons.
highlight = COLOR highlightedText = COLOR: highlight background and text color, e.g., for text selection and ListViews.
brightText = COLOR: text with good contrast to "dark" color.
link = COLOR linkVisited = COLOR: color used for drawing links and visited links (in RichText).
boxText = COLOR: color of box titles.
tabColor = COLOR: color of TabBar titles.

Index

M

MDL Tags

All

accel, Button, ToolButton, ButtonBar, MenuItem
acceptDrops, Control (Abstract)
activatedCommand, ComboBox
activeOffImage, Button, ToolButton, ButtonBar
activeOnImage, Button, ToolButton, ButtonBar
alignGroup, Control (Abstract), Field, Align Groups
alignGroup), Align Groups
alignGroupX, Control (Abstract), Align Groups
alignGroupY, Control (Abstract), Align Groups
alignTitle, Box
alignX, Control (Abstract)
alignX/Y, Table, Grid
alignY, Control (Abstract)
allowLinks, Label
allowRenaming, IconView
application, ScreenshotGallery
applicationSplashImage, MacroModule
applyButton, Field, VectorEdit
arrangement, IconView
author, Module (Abstract)
autoApply, TextView
autoArrange, IconView
autoComplete, ComboBox
autoPageStep, Slider
autoRaise, ToolButton
autoRepeat, Button, ToolButton
autoResize, Image
autoScale, ToolButton, ButtonBar
autoSize, FreeFloat, DynamicFrame
autoStart, MoviePlayer
backgroundColor, Viewer
backgroundImage, Module (Abstract)
bg, Control (Abstract), DefineStyle
bgMode, Control (Abstract)
border, Button, ButtonBar, Viewer
borderless, Window
boxFont, DefineStyle
boxText, DefineStyle
brightText, DefineStyle
browseButton, Field
browseFilter, Field
browseMode, Field
browseSelectedCommand, Field
browseTitle, Field
buddy, Label
button, Control (Abstract), DefineStyle
buttonBgMode, Control (Abstract)
buttonText, DefineStyle
callLater, FieldListener
cd, PathBrowser
cellSpacing, ListView
centerField, IntervalSlider
checkable, Box
checked, Box, MenuItem
checkedField, Box
checkList, ListView
checkListItemChangedCommand, ListView
childAlignGroup, Control (Abstract), Align Groups
childAlignGroupX, Control (Abstract), Align Groups
childAlignGroupY, Control (Abstract), Align Groups
children, EventFilter
class, MLModule, InventorModule
clickedCommand, ListView
clone, Viewer
color, Splitter
colors, DefineStyle
colors disabledColors, DefineStyle
colspan, Control (Abstract), Table
columnSeparator, ListView
comboBox, Field
comboCompletes, Field
comboField, Field, ComboBox
comboItems, Field
comboSeparator, Field, ComboBox
command, FieldListener, Button, ToolButton, HyperText, MenuItem, Accel, EventFilter
comment, Tag Data Types, Module (Abstract), Interface, Description
console, TextView
contentFile, DynamicFrame, WebView
contentString, WebView
contentStringBaseUrl, WebView
contentUrl, WebView
contextMenu, ListBox, ListView, IconView, MenuItem, DicomBrowser and DicomBrowserTable
contextMenuOnEmptyList, ListBox, ListView, IconView, DicomBrowser and DicomBrowserTable
control, EventFilter
currentChangedCommand, ListBox, ListView, IconView
dark, DefineStyle
dblClickedCommand, DicomBrowser and DicomBrowserTable
debug, EventFilter
delay, Viewer
deletionRequestedCommand, DicomBrowser and DicomBrowserTable
dependsOn, Control (Abstract)
deprecatedName, Tag Data Types, Module (Abstract), Interface, Description
derive, DefineStyle
destroyedCommand, Control (Abstract)
direction, Splitter, ButtonBar, Slider, IntervalSlider, ThumbWheel, Separator
directory, Deployment
disabledColors, DefineStyle
disabledOffImage, Button, ToolButton, ButtonBar
disabledOnImage, Button, ToolButton, ButtonBar
DLL, Tag Data Types, Deployment, MLModule, InventorModule
documentation, Module (Abstract)
doubleClickedCommand, ListBox, ListView, IconView
droppedFileCommand, Commands, Control (Abstract)
droppedObjectCommand, Control (Abstract)
duplicatesEnabled, ComboBox
eatEvent, EventFilter
edit, Field, CheckBox, VectorEdit, TextView
editable, ComboBox
editAlign, Field, NumberEdit, VectorEdit
editBg, Control (Abstract), DefineStyle
editBgMode, Control (Abstract)
editField, Field
editFont, DefineStyle
editMode, LineEdit
editText, DefineStyle
enableContextMenu, MoviePlayer
enabled, Control (Abstract), Field, CheckBox, MenuItem
enableEmbeddedMDL, WebView
enablePlugins, WebView
enableScriptingObjects, WebView
enumAutoFormat, Field, ButtonBar
exampleNetwork, Module (Abstract)
excludeFilter, DicomBrowser and DicomBrowserTable
expandTabs, Label
expandX, Control (Abstract), Horizontal, Separator, Align Groups
expandX/Y, Table, Grid, Splitter
expandY, Control (Abstract), Vertical, Separator, Align Groups
externalDefinition, Module (Abstract), MacroModule
family, DefineStyle
fg, DefineStyle
field, Tag Data Types, MenuItem, Accel
fieldDragging, Field
FieldListener, Commands
fields, Persistence
fileExtension, DicomBrowser and DicomBrowserTable
filename, MoviePlayer
filter, Tag Data Types, EventFilter
finalizeCommand, Commands
fixedHeight, Control (Abstract)
fixedPitch, DefineStyle
fixedWidth, Control (Abstract)
format, Field, NumberEdit, VectorEdit, Slider
frameLineWidth, Frame (Abstract)
frameMargin, Frame (Abstract)
frameMidLineWidth, Frame (Abstract)
frameShadow, Frame (Abstract)
frameShape, Frame (Abstract)
fullscreen, Window
fw, Control (Abstract)
genre, Tag Data Types, Module (Abstract), Module Genre Definition
Genre, Module Genre Definition
globalStop, Button, ToolButton
group, Tag Data Types, Module (Abstract), ModuleGroup Definition
h, Control (Abstract)
hasGroupInputs, InventorModule
hasViewer, InventorModule
header, ListView
height, Control (Abstract)
hidden, Interface, Description
hideCommand, PopupMenu, SubMenu
hideModule, Module (Abstract)
hierarchy, DicomBrowser and DicomBrowserTable
highlight, DefineStyle
highlightedText, DefineStyle
hintText, Field, LineEdit
hscroller, ScrollView, TextView
HSpacer, Empty
hybridMLModule, InventorModule
icon, MenuItem
image, Field, Button, ToolButton, ButtonBar, CheckBox, ComboBox, Label, Image
includeFilter, DicomBrowser and DicomBrowserTable
indent, Label
init, FieldListener
initCommand, Commands, Control (Abstract)
insertPolicy, ComboBox
internalName, Interface
italic, DefineStyle
item, Tag Data Types, Interface, Description, Field, ButtonBar, ComboBox
itemActivatedCommand, SubMenu
itemCollapsedCommand, ListView
itemExpandedCommand, ListView
itemRenamedCommand, ListView, IconView
items, Interface, Description, ButtonBar, ComboBox
itemTextPos, IconView
javaScriptInitCommand, WebView
key, Accel
keywords, Module (Abstract)
labelAlignGroup, Control (Abstract), Align Groups
layout, Box, ScrollView, ListView
legacyValue, Interface, Description
light, DefineStyle
link, DefineStyle
linkActivatedCommand, Label
linkClickedCommand, WebView
linkDelegation, WebView
linkHoveredCommand, Label
linkVisited, DefineStyle
listenField, FieldListener
loadFinishedCommand, WebView
loadProgressCommand, WebView
loadStartedCommand, WebView
lostFocusCommand, LineEdit
lowerField, IntervalSlider
margin, Vertical, Horizontal, Table, Grid
max, Tag Data Types, Interface, Description
maxCount, ComboBox
maximized, Window
maximumHeight, Control (Abstract)
maximumWidth, Control (Abstract)
maxItemWidth, IconView
maxLength, LineEdit
maxTextLength, IconView
maxw, Control (Abstract)
menuBar, MenuItem
mh, Control (Abstract)
mid, DefineStyle
midlight, DefineStyle
min, Tag Data Types, Interface, Description
minimumHeight, Control (Abstract)
minimumWidth, Control (Abstract)
minLength, Field, LineEdit, NumberEdit, VectorEdit, PathBrowser, DicomBrowser and DicomBrowserTable
mode, TabView, ColorEdit
module, Tag Data Types, Deployment, Panel
Module, Persistence
mouseButtonClickedCommand, ListView
mw, Control (Abstract)
name, Tag Data Types, Control (Abstract), Execute, PopupMenu, SubMenu, MenuItem, DynamicFrame, EventFilter
normalOffImage, Button, ToolButton, ButtonBar
normalOnImage, Button, ToolButton, ButtonBar
onlyOneInstance, MacroModule
pageStep, Slider
panel, Tag Data Types, Panel
Panel, Panel
panelByGroupTitle, Panel
panelName, Control (Abstract), Panel
pathDblClickedCommand, PathBrowser
pathSelectedCommand, PathBrowser
persistent, Interface, Description
ph, Control (Abstract)
popup, Viewer
popupDelay, ToolButton
popupMenu, Button, ToolButton, Viewer
posX, Control (Abstract)
posX/Y, FreeFloat
posY, Control (Abstract)
preferredHeight, Control (Abstract)
preferredWidth, Control (Abstract)
prepareEditCommand, ListView
pressedIndicatorField, Field, Slider, IntervalSlider, ThumbWheel
priority, Interface, Description
project, DicomBrowser and DicomBrowserTable
projectSource, MLModule, InventorModule
pw, Control (Abstract)
ratio, ThumbWheel
receiver, MenuItem
recursive, DicomBrowser and DicomBrowserTable
removed, Interface
resizeCommand, Control (Abstract)
resizeMode, IconView
returnPressedCommand, LineEdit, ListBox, ListView, IconView
richText, ListView
root, PathBrowser
rootDir, DicomBrowser and DicomBrowserTable
rootIsDecorated, ListView
rotationMode, ThumbWheel
Row, Table
rowSeparator, ListBox, ListView
scale, Control (Abstract), Slider, DefineStyle
scaleFactor, Image
scaleIconSetToMinSize, ToolButton
scriptOnly, MacroModule
seeAlso, Module (Abstract)
selectable, Label
selectedCommand, ListBox, IconView, DicomBrowser and DicomBrowserTable
selectionChangedCommand, ListBox, ListView, IconView, WebView
selectionMode, ListBox, ListView, IconView
shadow, Splitter, DefineStyle
shouldCloseCommand, Window
show, ButtonBar
showCommand, PopupMenu, SubMenu
showControls, MoviePlayer
showDicomFiles, DicomBrowser and DicomBrowserTable
showItemInternals, ButtonBar
showLineNumbers, TextView
size, DefineStyle
slider, Field
sliderSnap, Field
slot, MenuItem
snap, Slider, IntervalSlider, ThumbWheel
sortAscending, ListView
sortBy, PathBrowser
sortByColumn, ListView
source, Commands, Execute
SpacerX, Empty
SpacerY, Empty
spacing, Vertical, Horizontal, Table, Grid, Field, ButtonBar, VectorEdit, IconView
status, Module (Abstract)
step, Field, NumberEdit, IntervalSlider
stepstep, Field, NumberEdit
stretchX, Control (Abstract), Horizontal
stretchX/Y, Table, Grid, Splitter
stretchY, Control (Abstract), Vertical
strips, ButtonBar
style, Control (Abstract), Styles
styleSheetFile, Control (Abstract)
styleSheetString, Control (Abstract)
sunkenVectorLabels, Field, VectorEdit
tabColor, DefineStyle
tabDeselectedCommand, TabViewItem
tabEnabled, TabViewItem
tabFont, DefineStyle
tabIcon, TabViewItem
tabInitial, TabViewItem
tabSelectedCommand, TabViewItem
tabStopWidth, TextView
tabTitle, TabViewItem
tabTooltip, TabViewItem
text, TextView, HyperText
textAlign, Field
textAlignment, LineEdit, Label
textChangedCommand, ComboBox, LineEdit
textField, HyperText
textFile, HyperText
textFormat, TextView, Label
textPosition, ToolButton
textVisible, ProgressBar
textWrap, Label
tickmarks, Slider
title, Tag Data Types, Interface, Window, Box, Field, FieldLabel, Button, ToolButton, ButtonBar, CheckBox, ComboBox, TextView, HyperLabel, Label
titleField, Field, FieldLabel, Button, HyperLabel, Label
titleFile, HyperLabel
titleFont, DefineStyle
toggleField, ListView
toolTip, Tag Data Types
tooltip, Control (Abstract), ButtonBar
tracking, Slider, IntervalSlider, ThumbWheel
trim, Field, LineEdit, Label
type, Interface, Viewer
updateDelay, ListView
updateFieldWhileEditing, Field, LineEdit
upperField, IntervalSlider
UserGenres, Module Genre Definition
useSheet, Field
validator, LineEdit
value, Interface, Description, LineEdit
values, Interface, ListBox, ListView, Viewer
Viewer, Viewer
viewing, Viewer
visible, Control (Abstract)
visibleOn, Control (Abstract)
visibleRows, TextView, ListBox, ListView, PathBrowser, DicomBrowser and DicomBrowserTable
vscroller, ScrollView, TextView
VSpacer, Empty
w, Control (Abstract)
w/h, FreeFloat
wakeupCommand, Commands, Window
weight, DefineStyle
whatsThis, Tag Data Types, Control (Abstract), ButtonBar, MenuItem
width, Control (Abstract)
widthField, IntervalSlider
window, Panel
Window, Panel
wordWrap, IconView
wrap, Field, NumberEdit, TextView
wrapColumn, TextView
wrapsAround, ThumbWheel
x, Control (Abstract), Grid
x/y, Grid
x2, Control (Abstract), Grid
y, Control (Abstract), Grid
y2, Control (Abstract), Grid

Complex

Accel, Accel
Box, Box
Button, Button
ButtonBar, ButtonBar
ButtonBox, ButtonBox
CheckBox, CheckBox
ColorEdit, ColorEdit
ComboBox, ComboBox
Commands, Commands
Control, Control (Abstract)
DefineStyle, DefineStyle
Deployment, Deployment
Description, Description
DicomBrowser, DicomBrowser and DicomBrowserTable
DynamicFrame, DynamicFrame
Empty, Empty
EventFilter, EventFilter
Execute, Execute
Field, Field
FieldLabel, FieldLabel
FieldListener, FieldListener
Frame, Frame (Abstract)
FreeFloat, FreeFloat
Grid, Grid
Horizontal, Horizontal
HyperLabel, HyperLabel
HyperText, HyperText
IconView, IconView
Image, Image
Interface, Interface
IntervalSlider, IntervalSlider
InventorModule, InventorModule
Label, Label
LineEdit, LineEdit
ListBox, ListBox
ListView, ListView
MacroModule, MacroModule
MenuBar, MenuBar
MenuItem, MenuItem
MLModule, MLModule
Module, Module (Abstract)
MoviePlayer, MoviePlayer
NumberEdit, NumberEdit
Panel, Panel
PathBrowser, PathBrowser
Persistence, Persistence
PopupMenu, PopupMenu
PreloadDLL, Preloading DLLs
ProgressBar, ProgressBar
ScreenshotGallery, ScreenshotGallery
ScrollView, ScrollView
Separator, Separator
Slider, Slider
Splitter, Splitter
SubMenu, SubMenu
Table, Table
TabView, TabView
TabViewItem, TabViewItem
TextView, TextView
ThumbWheel, ThumbWheel
ToolButton, ToolButton
VectorEdit, VectorEdit
Vertical, Vertical
Viewer, Viewer
WebView, WebView
Window, Window

R

Related Files, Window

	Tip
	When you use string constants inside the expression, it is easiest to quote the MDL string with "* ... *" so that you do not have to escape the individual quotes of the string.

	Tip
	Not all controls currently support preferred width, some controls have their own default sizes.

	Tip
	This feature replaces and extends the old ILAB4 defaultSmall, defaultBig, ... styles, which should no longer be used.