EnvelopeView:
Filter:
Classes | GUI > Views

EnvelopeView : View : QObject : Object

A configurable view with nodes and connections
Subclasses: QEnvelopeView

Description

A view which can graphically display nodes at x/y coordinates, connection lines, cross-connections, node markers, and labels. All of the values for these are stored in arrays. While this view is typically used to make editable envelopes interfaces, it can be used to draw very complex interconnection graphs as well.

You can make the view display an Env using -setEnv. Note however that the view will work on a copy of the data of the Env object, therefore moving the nodes through the view will have no effect on the Env.

You can also define nodes with arrays of x and y values using -value, and the connections using -connect.

Appearance

The view supports two display styles: the default one draws nodes as small dots, with labels next to them, while another style draws nodes as rounded rectangles with labels drawn inside. See -style.

A label for each of the nodes can be set using -strings and -setString.

Interaction

Nodes can be selected and moved using mouse. Shift-clicking a node will add it to the selection.

You can also move selected nodes and change selection using keyboard. Pressing the arrow keys will move selected nodes (as long as -step is larger than 0). Pressing the left or right arrow keys while holding down Alt will select previous or next node, and holding down Shift will extend selection to the left or to the right. Other GUI kits may differ.

-keepHorizontalOrder allows you to enforce the order of nodes in horizontal direction to match their index order. In that case, node movement to the left and to the right will be restricted by the positions of their immediate neighbours. This is especially useful when EnvelopeView is used to display an Env.

-elasticSelection determines whether moving multiple nodes will be blocked altogether if any of the nodes meet an obstacle (the view bounds or a neighbour node), or only those individual nodes will be blocked.

Node selection can also be changed programmatically using -index, -selectIndex, and -deselectIndex. The current node can be moved programmatically using -x and -y.

Class Methods

Inherited class methods

Undocumented class methods

EnvelopeView.qtClass

Instance Methods

Data

.setEnv(env)

Sets an Env to be displayed by the view. The view will extract data from the Env object to display (times, values and curve types).

Any nodes existent prior to calling this method will be removed.

Arguments:

env

An Env.

.value

.value = anArray

value retrieves the node positions, returning an array in the format of the Argument below. value_(anArray) Sets the positions of the nodes, creating them if not existent.

If there were already existent nodes and their amount is different than the amount of x/y pairs in the argument, nodes will be added or removed (in order of creation reversed) until the amounts match, and then the new values will be applied.

Arguments:

anArray

An Array containing two other Arrays, of which one contains the horizontal and the other the vertical position of the new nodes. The values must be between 0 and 1. For example: [[ x1, x2, x3, ... ], [ y1, y2, y3, ... ]]

.valueAction = anArray

Sets -value to the argument and triggers the -action.

.x

.x = aFloat

The horizontal position of the current node.

Arguments:

aFloat

A Float between 0 and 1.

.y

.y = aFloat

The vertical position of the current node.

Arguments:

aFloat

A Float between 0 and 1.

.currentvalue

.currentvalue = aFloat

Synonym for -y.

.curves

.curves = curves

The shapes of connections between nodes. See below for the valid objects that describe a shape.

If a single shape is given, it will be applied to all the existing nodes. If an Array of shapes is given, each of its elements will be applied to an existing node, in order of index.

A connection curve shape applied to a node will determine the shape of the connections originating at that node. If no connections have been created using -connect, the origin node of a connection is the one with lower index. If there are such connections however, their origin is the node that was passed as the first argument to -connect.

Arguments:

curves

The valid objects to describe a shape are listed in Env: *new. The argument can be either a single, or an Array of those values.

.strings = anArray

The labels of the nodes.

NOTE: In order for the labels to be visible, you might need to ensure that the -strokeColor contrasts the -fillColor (depending on how the view draws the nodes and the labels).

Arguments:

anArray

An Array of Strings.

.setString(index, string)

Sets the label of the node at the given index.

NOTE: In order for the label to be visible, you might need to ensure that the -strokeColor contrasts the -fillColor (depending on how the view draws the nodes and the labels).

Arguments:

index

the index of the node.

string

A String.

.setFillColor(index, color)

Sets the color used to draw the inside of the node at the given index.

Arguments:

index

An Integer.

color

A Color.

.setThumbWidth(index, width)

Sets the width of the node at the given index.

NOTE: For compatibility with existing code, this will set the -style to 'rects'.

Arguments:

index

An Integer.

width

An Integer.

.setThumbHeight(index, height)

Sets the height of the node at the given index.

NOTE: For compatibility with existing code, this will set the -style to 'rects'.

Arguments:

index

An Integer.

height

An Integer.

.setThumbSize(index, size)

Sets both width and height of the node at the given index to size.

Arguments:

index

An Integer.

size

An Integer.

.connect(source, targets)

Removes any connections created when the -value was set, and then creates new ones from the node at index given in the first argument to each of the nodes at indexes given in the second argument.

Arguments:

source

An Integer - the index of the node to become one end of all the new connections.

targets

An Array of Integers - indexes of nodes, each to become the second end to a new connection created.

.selection

Returns an array of indexes of all selected nodes.

Appearance

.style

.style = style

One of the following drawing styles:

NOTE: For compatibility with existing code, calling any of -thumbWidth, -thumbHeight, -setThumbWidth, or -setThumbHeight will automatically switch style to 'rects'. You can still set a different style afterwards.

Arguments:

style

One of the symbols: \dots or \rects. Alternatively, an integer 0 or 1, for each style respectively.

Returns:

An integer 0 or 1.

.drawLines

.drawLines = aBool

Whether to draw the connections between the nodes.

Arguments:

aBool

A Boolean.

.drawRects

.drawRects = aBool

Whether to draw the nodes

Arguments:

aBool

A Boolean.

.gridOn

.gridOn = aBool

Whether to draw the grid.

Arguments:

aBool

A Boolean.

.grid

.grid = aPoint

The resolution of the grid.

Arguments:

aPoint

A Point of which x and y correspond to grid spacing on the horizontal and the vertical axis, respectively. If one of the two is 0, the grid on that axis will not be drawn.

.thumbWidth = width

Sets the width of all nodes.

NOTE: For compatibility with existing code, this will set the -style to 'rects'.

Arguments:

width

An Integer.

.thumbHeight = height

Sets the height of all nodes.

NOTE: For compatibility with existing code, this will set the -style to 'rects'.

Arguments:

height

An Integer.

.thumbSize = size

Sets both -thumbWidth and -thumbHeight to the argument.

.strokeColor

.strokeColor = color

The color used to draw the connections and the node labels.

Arguments:

color

A Color.

.fillColor

.fillColor = aColor

The default color used to draw the nodes. If the color of a specific node has been set using -setFillColor, it will take precedence.

Arguments:

aColor

A Color.

.selectionColor

.selectionColor = color

The color of a node when it is selected.

Arguments:

color

A Color.

.gridColor

.gridColor = color

The color of the grid.

Arguments:

color

A Color.

.colors_(strokeColor, fillColor)

Sets the -strokeColor and the -fillColor to the arguments, respectively.

Interaction

.index

.index = index

The index of the current node, i.e. the node affected by -x and -y methods.

This is the selected node with lowest index, or -1 if no selection.

Arguments:

index

An Integer.

.lastIndex

The last node selected, regardless of the current state of selection, or -1 if no node has yet been selected.

.selectIndex(index)

Selects the node at given index and makes it the current one, i.e. -currentvalue will relate to that node. As a special case, if the argument is -1 all nodes will be deselected.

Arguments:

index

An Integer.

.deselectIndex(index)

Deselects the node at given index.

NOTE: Not available in Cocoa GUI.

Arguments:

index

An Integer.

.editable

.editable = aBool

Whether any node is editable.

Arguments:

aBool

A Boolean.

.setEditable(index, flag)

Sets whether the node at given index is editable. Regardless of this, no node will be editable unless -editable is true.

Arguments:

index

An Integer.

flag

A Boolean.

.step

.step = aFloat

Makes the nodes snap (i.e. quantized) to the nearest multiple of the argument. Unless this is larger than 0, nodes will not be movable using keyboard.

Arguments:

aFloat

A Float.

.keepHorizontalOrder

.keepHorizontalOrder = bool

Whether the position of nodes on the horizontal axis shall be restricted by their immediate neighbours (in order of their index).

Setting this to true will immediately modify the positions of existing nodes to match the order.

Arguments:

bool

A Boolean.

.elasticSelection

.elasticSelection = bool

Whether the relative positions of nodes within the selection can change when the selection is moved using mouse or keyboard, in order to adapt to obstacles (the view bounds or, in case -keepHorizontalOrder is true, a neighbour node).

If this is false, movement of multiple nodes will be blocked altogether when an obstacles is met, otherwise only the individual nodes will be blocked at their obstacles.

Arguments:

bool

A Boolean.

Actions

.action

.action = func

From superclass: View

The action object evaluated whenever the user moves a node.

.metaAction

.metaAction = function

The action object evaluated whenever the user moves a node while the Ctrl key is pressed.

.defaultKeyDownAction(char, modifiers, unicode, keycode, key)

From superclass: View

Implements the default behavior on key presses.

The default behavior is defined in the C++ implementation of the view instead of this method. See View: Key and mouse event processing for explanation of how to override the behavior.

Drag and drop

.defaultGetDrag

Returns:

The -value.

.defaultCanReceiveDrag

Returns:

True for any drag data, but the data should be in the same format as -value.

.defaultReceiveDrag

If the drag data is of the acceptable form (see -defaultCanReceiveDrag above), sets -value using that data.

Inherited instance methods

Undocumented instance methods

.asEnv(curves, timeScale: 1, levelScale: 1, levelBias: 0, releaseNode, loopNode: 0)

From extension in /Library/Application Support/SuperCollider/Extensions/sc3-plugins-3.13.0/SC3plugins/BhobUGens/classes/osx/asEnv.sc

.doMetaAction

Examples

Use as envelope view

Use shift click to select/unselect the points

Show boxes with a string in it: