GMCurveEnvView
Extension
ExtensionDescription
GMCurveEnvView is a widget that allows interaction with an Env.
It provides handles on every level of the Env, allowing to reshape it with the cursor. It also provides handles on every segment, allowing to change the curvature of the selected segment. The CTRL + LEFT MOUSE BUTTON will add new points, RIGHT MOUSE BUTTON will delete points.
In SuperCollider, Envs have a default maximum number of values, which is defined at SynthDef creation. This needs to be assigned to the GMCurveEnvView using maxSize to prevent the user from exceeding the length of the Env.
This widget only manipulates Envs with integer curvatures values. Assigning an Env with other curvatures types (e.g. \exp, \sin, ...) will convert those curvatures to 0 (i.e. linear curvatures). By default, assigning a 'wrong' Env will reevaluate the associated action so the displayed Env corresponds to the Env currently in use. Consequently, associating an action and a maxSize before assigning an env to the widget is preferable.
In SuperCollider, Envs are passed as references. To avoid issues, GMCurveEnvView makes a copy of the provided Env, and also makes a copy of its own internal Env when its action is triggered. This means that if you modify the Env that is currently displayed without using the widget, the widget will not update automatically : you will need to reassign the Env to reflect modifications.
GMCurveEnvViews drawFunc relies heavily on mouseMoveAction. In order to function properly, this means that every of its parent views should have acceptsMouseOver set to true. By default, on creation, GMCurveEnvView will recursively set acceptsMouseOver to true for every one of its parents, after a 100ms delay, which should ensure the algorithm works properly. However, if you are reagencing the view hierarchy, you will need to ensure manually that all of its parents have this property correctly set.
Currrently, GMCurveEnvView only supports linear distribution on its Y axis.
Class Methods
.new
Creates a new instance of GMCurveEnvView.
Its graphical properties are defined by its associated GMStyle.
Instance Methods
Interaction
.env
Sets or gets the manipulated Env.
Two checks are passed on the new env : if the new env is longer than the allowed max size, it will be shrunk to the max allowed size. Then, for every segment of the env, if its curvature is not an integer (or not \lin), it will be set to a 0 curvature.
Since those checks might have modified the env, this would mean the displayed env is not in sync with the original env. env takes an additional boolean argument which, if set to true, will reevaluate the action if the env has been modified, to ensure synchronicity.
.action
Sets or gets the function to evaluate when the widget is used. This Function takes a single Env argument. Please note that the env passed as argument will be a copy of GMCurveEnvView internal env.
Arguments:
| aFunction |
A Function with a single argument. |
.actionOnMove
Sets or gets wether the associated action should be evaluated every time the user moves a point or a curvature. If set to false, action will only evaluate on mouse up and down actions.
.timeScale
Sets or gets the portion of time the width of the widget represents, in seconds. For example, a value of 2.0 means that a point on the right border of the widget defines the level of the env 2.0 seconds after it started playing. In the same way, a point exactly in the middle of the widgets horizontal axis would represent the level of the env 1 second after it started playing. Setting this value too low can prevent selecting points which time are greater than the current timeScale.
Arguments:
| aNumber |
.yMin
Sets or gets the value the vertical axis bottom border corresponds to. This is purely visual and won't affect envs levels. Setting this value too high might prevent selecting points which level is lower. Will disable lastLevelIsZero is different from 0.
Arguments:
| aNumber |
.yMax
Sets or gets the value the vertical axis top border corresponds to. This is purely visual and won't affect envs levels. Setting this value too low might prevent selecting points which level is higher
Arguments:
| aNumber |
.lastLevelIsZero
Sets or gets wether the last point should be constrained to a value of 0. This is mostly useful for enveloppes that control an amplitude parameter.
.maxSize
Sets or gets the max number of points that the widget allows to create. Since SynthDef have a fixed maximum enveloppe size defined at creation, this allows to adapt the GMCurveEnvView accordingly. Addition of new points will be disabled once this maximum is reached.
Arguments:
| anInteger |
An Integer. |
Grahics
.modColor
Sets or gets the Color used to display new point preview and highlight hovered handles.
.displayHelpers
Sets or gets wether helpers should be drawn. Helpers will display a grid pattern on the background of the widget to ease point placement.
.xHelpers
Sets or gets the number of vertical lines displayed on the background of the widget, not counting extremities, when helpers are displayed.
.yHelpers
Sets or gets the number of horizontal lines displayed on the background of the widget, not counting extremities, when helpers are displayed.
.helpersWidth
Sets or gets the helpers grid width, in pixel.
.helpersFontSize
Sets or gets the font size of helpers labels, in pixel.
.xRoundValue
Sets or gets the rounding value of horizontal helpers labels.
.yRoundValue
Sets or gets the rounding value of vertical helpers labels.
Internal Methods
.draw
The function associated to the Views drawFunc. Shouldn't be modified.
.prAddPoint
.prCheckHovering
.prCollideWith
.prDrawHandles
.prDrawHelpers
.prDrawLine
.prDrawNewPoint
.prDrawPoints
.prFillShape
.prGetHandlePositions
.prGetPointPositions
.prMousePosInbounds
.prMoveHandle
.prMovePoint
.prRemovePoint
Examples
A simple example, with a GMCurveEnvView controlling a sine wave amplitude:
A more complex example, with 3 controls : amplitude, frequency and panning. A slider also allows to modify widgets timeScales:
link::GraphicalModule/Classes/GMCurveEnvView::