/ HALion Developer Resource / HALion Macro Page / Templates /

Envelope

On this page:

Description
Template Properties
Template Parameters
Components inside the Template

Envelope

Description

The Envelope template allows you to edit HALion's multi-stage envelopes. The template contains controls for scrolling and zooming the envelope and for setting the envelope mode or the values of the selected node, for example. The controls must be part of the template and they must use the UI variables as defined in the template to connect with the Envelope View Control.

❕ The Envelope View Control cannot be created manually in the GUI Tree. Please load the template from the Basic Controls library to use it. You can adapt the look and feel of the template to the requirements of your macro page with the Properties and Colors as described below. If certain controls are not required or wanted, they can be removed.

To explore the functionality and connections:

Load the Init Basic Controls.vstpreset from the Basic Controls library.
Open the Macro Page Designer, go to the GUI Tree and navigate to "Pages > Envelope Page".
Select "Envelope" and click Edit Element to examine the template.

Template Properties

Poperty	Description
Name	The name of the element. This name will be displayed in the GUI Tree.
Position/Size	Position X, Position Y, Width, Height: Position and size of the element in pixels. Position X/Y defines the position of the upper left corner.
Attach	Defines how an element behaves when its parent element is resized. You can set the following parameters: Left: If the parent element is resized, the element remains attached to left edge, with the specified ratio. Right: If the parent element is resized, the element moves relatively to the right edge, with the specified ratio. Top: If the parent element is resized, the element remains attached to top edge, with the specified ratio. Bottom: If the parent element is resized, the element moves relatively to the bottom edge, with the specified ratio. Left + Right: If the parent element is resized, the element is resized horizontally relatively to the left and right edges, with the specified ratio.
Tooltip	Text that appears as a tooltip when the mouse hovers over the element.
Template	Determines the template to be referenced.

Template Parameters

Parameter	Description
Triplet	Connect this to the Triplet parameter of the envelope.
Mode	Connect this to the Mode parameter of the envelope.
Play Pos	Connect this to the PlaybackPos parameter of the envelope.
Loop Start	Connect this to the LoopStart parameter of the envelope.
Loop End	Connect this to the LoopEnd parameter of the envelope.
Env Points	Connect this to the Envelope Points parameter of the envelope.
Sync	Connect this to the Sync parameter of the envelope.
Sustain	Connect this to the SustainIndex parameter of the envelope.

Components inside the Template

Envelope Template

UI Variables

These variables are needed to allow the communication between the Envelope View and other controls in the template.

Variable	Description	Type	Range
beat	Time in beats.	rational	n.a.
curve	Curvature of the selected node segment.	float	-10 - 10
level	Level of the selected node.	float	0 - 100
time	Time of the selected note.	float	0 - 30000
index	Index of the selected node.	integer	0 - 128
fixed	Fixed mode of the envelope.	integer	0, 1
syncnote	Specifies the note grid.	stringlist	1/1, 1/2, 1/4, 1/8, 1/16, 1/32, 1/64, 1/128, 1/256

Controls and Subtemplates

Item	Description
Edit	This Group contains controls that allow you to draw shapes, adjust the selected node and further options of the envelope. Time: A Stack with two templates to either set the time of a node in ms or fractions of a beat. The Value of the Stack is exported as `Sync` and should be connected to the Sync parameter of the corresponding envelope in the zone. Time ms/Time Beat: The Value of the "Time ms" and the "Time Beat" templates must be set to the UI variables `@time` and `@beat` respectively. This way, they are connected to the corresponding properties of the Envelope View, which use the same UI variables. Mode: A menu template. Its Value is exported as `Mode` and should be connected to the Mode parameter of the corresponding envelope in the zone. Sync: A switch template. Its Value is exported as `Sync` and should be connected to the Sync parameter of the corresponding envelope in the zone. Fixed: A switch template. Its Value is connected to the corresponding property of the Envelope View by the UI variable `@fixed`. Curve: A valuebox template to adjust the curvature of the selected node. Its Value is connected to the corresponding property of the Envelope View by the UI variable `@curve`. Level: A valuebox template to adjust the level of the selected node. Its Value is connected to the corresponding property of the Envelope View by the UI variable `@level`. Index: A valuebox template to select the index of the node to be edited. Its Value is connected to the corresponding property of the Envelope View by the UI variable `@index`. SyncNote: A Disable view with two templates: Sync Note and Triplet. The Value of the Disable view is exported as `Sync` and should be connected to the Sync parameter of the corresponding envelope in the zone. If Sync is active, the Disable view becomes active too and the contained templates can be used to set the Sync Note and Triplet parameters of the envelope. Sync Note: A menu template. Its Value must be set to `@syncnote`, a stringlist UI variable that defines the allowed note values. It is also connected to the corresponding property of the Envelope View, which uses the same UI variable. Triplet: A switch template. Its Value is exported as `Triplet` and should be connected to the Triplet parameter of the corresponding envelope in the zone.
EnvView	This Group contains a group with controls for scrolling and zooming the envelope and the Envelope View. Scroll & Zoom: This Group contains controls that allow you to scroll and zoom the envelope. Scrollbar: A Range Slider to reach areas of the envelope that are not visible through the zoom. The Low Value of the Range Slider must be set to `@ScrollMin` and the High Value must be set to `@ScrollMax`. Background: A background bitmap for the scrollbar. Zoom Out: A switch template that allows you to zoom out the envelope. Its Value must be set to `@ZoomOut`. Zoom In: A switch template that allows you to zoom in the envelope. Its Value must be set to `@ZoomIn`. Zoom Alternate: A switch template that toggles between the last zoom state or completely zoomed out. Its Value must be set to `@StateA.` Zoom1: A switch template to activate zoom state 1. Its Value must be set to `@State1`. Zoom2: A switch template to activate zoom state 2. Its Value must be set to `@State2`. Zoom3: A switch template to activate zoom state 3. Its Value must be set to `@State3`. Envelope View: The graphical envelope editor. The properties EnvValue, Mode, Sync, Triplet, Loop Start, Loop End, Sustain and Play Pos are exported and thus are available as template parameters. They should be connected to the parameters of the corresponding envelope in the zone. The Value of the properties SyncNote, Fixed, Index, Level, Time, Beat and Curve is set to the corresponding UI variable. This way, each property is connected to one of the control templates mentioned above. See Envelope View Control for further details.
Env Background	The background bitmap for the envelope.

Envelope View Control

Properties

In addition to standard properties like size, position, etc., the Envelope View provides further properties and colors to customize its appearance and behavior.

Poperty	Description
Name	The name of the element. This name will be displayed in the GUI Tree.
Position/Size	Position X, Position Y, Width, Height: Position and size of the element in pixels. Position X/Y defines the position of the upper left corner.
Attach	Defines how an element behaves when its parent element is resized. You can set the following parameters: Left: If the parent element is resized, the element remains attached to left edge, with the specified ratio. Right: If the parent element is resized, the element moves relatively to the right edge, with the specified ratio. Top: If the parent element is resized, the element remains attached to top edge, with the specified ratio. Bottom: If the parent element is resized, the element moves relatively to the bottom edge, with the specified ratio. Left + Right: If the parent element is resized, the element is resized horizontally relatively to the left and right edges, with the specified ratio.
Tooltip	Text that appears as a tooltip when the mouse hovers over the element.
Style	Bipolar: Activate this for bipolar envelopes like pitch or pan. Scrollbar: If this is active, the view can be scrolled and zoomed. Cross: Shows crosslines when editing nodes. Grid: Shows a time grid. Play Pos: Shows the current playback position on the curve. Nodes: Shows nodes. Add/Rem: Allows adding and removing of nodes. Deactivate this option to provide an ADSR envelope with a fixed number of nodes, for example. Sel Node: Allows you to select a node. Sustain: Shows a sustain line. For this, an envelope Mode with sustain must be active. Loop: Shows an overlay for the loop region. For this, the envelope Mode must be set to Loop. Free End: Allows you to move the last node of a unipolar envelope away from the zero line.
Env Value	Exported as `Env Points`. See Template Parameters above.
Mode	Exported as `Mode` See Template Parameters above.
Sync	Exported as `Sync` See Template Parameters above.
Triplet	Exported as `Triplet` See Template Parameters above.
SyncNote	Connected to the corresponding control template by the UI variable `@syncnote`.
Fixed	Connected to the corresponding control template by the UI variable `@fixed`.
Tool	Not used in this template. See Envelope Shaper template for details of this property.
ShapeSave	Not used in this template. See Envelope Shaper template for details of this property.
ShapeSelect	Not used in this template. See Envelope Shaper template for details of this property.
Shape	Not used in this template. See Envelope Shaper template for details of this property.
Index	Connected to the corresponding control template by the UI variable `@index`.
Level	Connected to the corresponding control template by the UI variable `@level`.
Time	Connected to the corresponding control template by the UI variable `@time`.
Beat	Connected to the corresponding control template by the UI variable `@beat`.
Curve	Connected to the corresponding control template by the UI variable `@curve`.
Loop Start	Exported as `Loop Start`. See Template Parameters above.
Loop End	Exported as `Loop End`. See Template Parameters above.
Sustain	Exported as `Sustain`. See Template Parameters above.
Play Pos	Exported as `Play Pos`. See Template Parameters above.
Min X	Defines the minimum value of the horizontal zoom.
Max X	Defines the maximum value of the horizontal zoom.
Min Y	Defines the minimum value of the vertical zoom.
Max Y	Defines the maximum value of the vertical zoom.

Colors

❕ Some colors are available only if the corresponding Style options are enabled.

Poperty	Description
Line	Line color between the nodes.
Fill	Fill color of the nodes.
FillSelected	Fill color of the selected nodes.
FrameFocus	Frame color of the focussed node.
Frame	Frame color of the nodes.
Hover	Hover frame color of the nodes.
Sustain	Color of the Sustain node and line.
Synced	Dot color of nodes that are aligned to the sync grid.
Crosshair	Node edit crosshair color.
Play Pos	Color of the playback position indicator.
Border	Overall border color.
Grid V	Vertical grid color.
Grid V2	Vertical fine grid color.
Grid V3	Vertical fine grid color.
Grid H	Horizontal grid color.
Grid H2	Horizontal fine grid color.
Font	Timeline font color.
Selector	Selection area fill color.
SelFrame	Selection area frame color.
Zoom	Zoom area fill color.
ZoomFrame	Zoom area frame color.
Loop	Loop area fill color.
LoopFrame	Loop area frame color.

HALion 7.0.0