Code Generator Shape

Explains the visual appearance, usage, context menus and properties of the code generator shape and the concept of code generation.

The Code Generator and Consts Code Generator shapes are visual representatives for executing and parametrizing the code generator. The code generator is embedded as a Visual Basic for Applications module into the state machine diagram .vsd file.

The Code Generator and Consts Code Generator shapes must be connected with the root region shape of the state machine diagram. Through this connection the code generator knows for which diagram to generate code.

Figure 1: Code generator shape connected to root region

The Ctrl+G application shortcut executes the code generation of all Code Generator shapes of the current diagram and writes the output to the Target File shown in the Code Generator shape.

The Code Generator shape moves together with the root region shape to which it is connected. Dragging the shape will disconnect it from the region.

The yellow diamond at the lower right corner of the Code Generator shape (visible when the shape is selected) allows to position the shape relative to the connected region.

What Do You Want to Do?

How code generation works

The code generator algorithm traverses the state machine diagram and builds an internal tree of regions, states and transitions, similar to the structure of regions, states and transitions in the StaMaStateMachineTemplate.

After creating the internal tree, a visitor pattern algorithm traverses all nodes of the internal tree and evaluates Visual Basic Script expressions configured in the Code Generator shape properties that return a string that will be written to the target file. The Visual Basic Script expressions from the Code Generator shape may use variables as defined below. Modifying the expressions in the Code Generator allows to customize the generated code.

Finally all generated text output is surrounded with the code marker frame and the target file is updated with this block of lines.

Code Generator Shape Properties

The code generator shape has a properties dialog that can be opened either by double clicking on the shape info rectangle or by opening the context menu of the shape info rectangle and executing the menu item Properties....

Figure 2: Code generator basic properties

The properties are as follows:

Property	Purpose
Custom1, Custom2, Custom3, Custom4	These properties are general purpose text fields that may be referenced in the code generator Visual Basic Script expressions. Their meaning depends on the usage within the code generator Visual Basic Script expressions. The Prompt field at the bottom of the properties dialog shall give a hint for their intended meaning. See also Code Generator Shape for more details about customization of the code generator.
Target File	Defines the target file for the code generator. As long as the value is not manually changed, the path will be in the same directory as the state machine diagram .vsd file and have the same file name, but with a .cs file extension.
Ident	Defines a unique identifier needed to identify the code chunk generated from this code generator shape within the .cs file. The default value is usually unique for a state machine diagram but can be changed if needed.

Code Generator Shape Context Menu

The code generator shape has the following additional context menu items:

Context Menu Item	Purpose
Generate Code	Executes the code generator for this code generator shape. The generated code chunk can be found in the file specified by the Target File property and is tagged with the unique identifier of the Ident property.
Open Target File	Opens the the file specified by the Target File property in the system default editor for .cs files.
Show Advanced Properties	Expands or collapses the display of advanced code generator Visual Basic Script expressions in the properties dialog.

Code generator expressions and variables

The advanced properties of the Code Generator shape contain Visual Basic Script expressions that generate strings whenever the code generator traverses a particular node of the internal tree as described in Code Generator Shape

Figure 3: Code generator advanced properties

The advanced properties are as follows:

Property	Purpose
Code Chunk Marker	Provides a Visual Basic Script expression that returns the frame for the generated code chunk. The returned string is used and needed to identify the code chunk when generated code chunk is updated (generated again)).
Comment	Provides a Visual Basic Script expression that formats a commented line. The code generator uses this expression to add context information like the Microsoft Visio .vsd file, the generation date and time and the gode generator version.
Region Begin	Provides a Visual Basic Script expression that is evaluated when the code generator starts to run across a region containing simple or composite states.
Region End	Provides a Visual Basic Script expression that is evaluated when the code generator has finished a region.
State Begin	Provides a Visual Basic Script expression that is evaluated when the code generator starts to run across a state that may be a composite state with orthogonal sub-regions.
State End	Provides a Visual Basic Script expression that is evaluated when the code generator has finished a state.
Transi Begin	Provides a Visual Basic Script expression that is evaluated when the code generator starts to run across a transition, before the source or target definition. Transition source and target states are handled through the Transi From/To Begin, Transi From/To More and Transi From/To End.
Transi End	Provides a Visual Basic Script expression that is evaluated when the code generator has finished a transition.
Transi From/To Begin	Provides a Visual Basic Script expression that is evaluated when the code generator starts either a source or a target definition. Writing state names is handled through the Transi Segment property.
Transi From/To More	Provides a Visual Basic Script expression that is evaluated when the code generator runs across an additional transition segment of a source or a target definition. This expression is intended to separate state names of the transition source or target state configuration.
Transi From/To End	Provides a Visual Basic Script expression that is evaluated when the code generator has finished a transition source or a target definition.
Transi Segment	Provides a Visual Basic Script expression that is evaluated when the code generator runs across a transition segment within a transition source or a target definition.

The following line shows the default expression of the Code Generator shape for the State Begin property which is evaluated when the code generator starts traversing a state node and its sub-tree:

=Custom3 & Custom1 & ".State(" & State & ", " & IIf(Len(EntryAction)>0, EntryAction, "null") & ", " & IIf(Len(ExitAction)>0, ExitAction, "null") & IIf(Len(DoAction)>0, ", " & DoAction, "") & ");" & vbNewLine

These string expressions may use all visual basic script functions plus the following special functions:

An inline IIf function as known from VBA.
Numerical two argument Min and Max functions.
The special purpose IsDone and MarkDone functions that allow to query and maintain a set of identifiers within the code generator expressions. These methods are intended to support suppression of duplicate code generation for enumerations of event signals or actions. The methods require two parameters, the first parameter is a string that defines the scope and the second parameter is the string for the identifier.
The following expression in the Transi End advanced property will generate a list of event signal names without duplicates:
=IIf((Len(EventSignal)>0) And Not IsDone("EventSignal", EventSignal), Custom3 & EventSignal & "," & vbNewLine & MarkDone("EventSignal", EventSignal), "")
Every invocation of the MarkDone function adds the identifier to the table of identifiers, subsequent visits of the code generator expression will check through the IsDone function if the identifier was already encountered.

In order to write the state names, entry actions, exit actions, transition actions and similar, the expressions may reference a set of variables that correspond with the properties of the region, state and transition shapes. The following table lists these variables and the Code Generator shape properties in which they are defined:

Figure 4: Code generator variables

The code generator is a Visual Basic for Applications algorithm embedded into the state machine .vsd file. It can be inspected by opening the built-in Microsoft Visio Visual Basic for Applications editor and debugger through the shortcut Alt+F11 or through the menu (View Code entry in Developer ribbon). The Public Sub GenerateCodeAll() is a suitable starting point for stepping through with the debugger.