571 lines
15 KiB
Racket
571 lines
15 KiB
Racket
#lang scribble/manual
|
|
@(require (for-label racket))
|
|
|
|
@title{EnvelopeView}
|
|
A configurable view with nodes and connections@section{categories}
|
|
GUI>Views
|
|
@section{related}
|
|
Classes/MultiSliderView, Classes/SCEnvelopeEdit
|
|
|
|
@section{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 link::Classes/Env:: using link::#-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 link::#-value::, and the connections using link::#-connect::.
|
|
|
|
@section{SUBSECTION}
|
|
Appearance
|
|
|
|
The view supports two strong::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 link::#-style::.
|
|
|
|
A strong::label:: for each of the nodes can be set using link::#-strings:: and link::#-setString::.
|
|
|
|
@section{SUBSECTION}
|
|
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 link::#-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.
|
|
|
|
link::#-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 link::Classes/Env::.
|
|
|
|
link::#-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 link::#-index::, link::#-selectIndex::, and link::#-deselectIndex::. The link::#-index#current:: node can be moved programmatically using link::#-x:: and link::#-y::.
|
|
|
|
@section{INSTANCEMETHODS}
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Data
|
|
|
|
@section{METHOD}
|
|
setEnv
|
|
Sets an link::Classes/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.
|
|
|
|
@section{argument}
|
|
|
|
An Env.
|
|
|
|
|
|
@section{METHOD}
|
|
value
|
|
|
|
@racketblock[value:: retrieves the node positions, returning an array in the format of the Argument below. ]
|
|
|
|
@racketblock[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.
|
|
|
|
]
|
|
@section{argument}
|
|
|
|
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:
|
|
@racketblock[ [[ x1, x2, x3, ... ], [ y1, y2, y3, ... ]] ::
|
|
|
|
]
|
|
@section{METHOD}
|
|
valueAction
|
|
Sets link::#-value:: to the argument and triggers the link::#-action::.
|
|
|
|
@section{METHOD}
|
|
x
|
|
The horizontal position of the emphasis::current:: node.
|
|
|
|
@section{argument}
|
|
|
|
A Float between 0 and 1.
|
|
|
|
@section{METHOD}
|
|
y
|
|
The vertical position of the emphasis::current:: node.
|
|
|
|
@section{argument}
|
|
|
|
A Float between 0 and 1.
|
|
|
|
@section{METHOD}
|
|
currentvalue
|
|
Synonym for link::#-y::.
|
|
|
|
@section{METHOD}
|
|
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 link::#-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 link::#-connect::.
|
|
|
|
@section{argument}
|
|
|
|
The valid objects to describe a shape are listed in link::Classes/Env#*new::. The argument can be either a single, or an Array of those values.
|
|
|
|
@section{METHOD}
|
|
strings
|
|
The labels of the nodes.
|
|
|
|
@section{note}
|
|
In order for the labels to be visible, you might need to ensure that the link::#-strokeColor:: contrasts the link::#-fillColor:: (depending on how the view draws the nodes and the labels).
|
|
::
|
|
|
|
@section{argument}
|
|
|
|
An Array of Strings.
|
|
|
|
@section{METHOD}
|
|
setString
|
|
Sets the label of the node at the given index.
|
|
|
|
@section{note}
|
|
In order for the label to be visible, you might need to ensure that the link::#-strokeColor:: contrasts the link::#-fillColor:: (depending on how the view draws the nodes and the labels).::
|
|
|
|
@section{argument}
|
|
index
|
|
the index of the node.
|
|
|
|
@section{argument}
|
|
string
|
|
A String.
|
|
|
|
@section{METHOD}
|
|
setFillColor
|
|
Sets the color used to draw the inside of the node at the given index.
|
|
|
|
@section{argument}
|
|
index
|
|
An Integer.
|
|
@section{argument}
|
|
color
|
|
A Color.
|
|
|
|
@section{METHOD}
|
|
setThumbWidth
|
|
Sets the width of the node at the given index.
|
|
|
|
@section{NOTE}
|
|
For compatibility with existing code, this will set the link::#-style:: to strong::'rects'::. ::
|
|
|
|
@section{argument}
|
|
index
|
|
An Integer.
|
|
@section{argument}
|
|
width
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
setThumbHeight
|
|
Sets the height of the node at the given index.
|
|
|
|
@section{NOTE}
|
|
For compatibility with existing code, this will set the link::#-style:: to strong::'rects'::. ::
|
|
|
|
@section{argument}
|
|
index
|
|
An Integer.
|
|
@section{argument}
|
|
height
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
setThumbSize
|
|
Sets both width and height of the node at the given index to
|
|
@racketblock[size::.
|
|
|
|
]
|
|
@section{argument}
|
|
index
|
|
An Integer.
|
|
@section{argument}
|
|
size
|
|
An Integer.
|
|
|
|
|
|
@section{METHOD}
|
|
connect
|
|
Removes any connections created when the link::#-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.
|
|
|
|
@section{argument}
|
|
source
|
|
An Integer - the index of the node to become one end of all the new connections.
|
|
@section{argument}
|
|
targets
|
|
An Array of Integers - indexes of nodes, each to become the second end to a new connection created.
|
|
|
|
@section{METHOD}
|
|
selection
|
|
Returns an array of indexes of all selected nodes.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Appearance
|
|
|
|
@section{METHOD}
|
|
style
|
|
|
|
|
|
One of the following drawing styles:
|
|
|
|
@section{list}
|
|
|
|
|
|
## strong::'dots':: - nodes are drawn as small dots within a larger circle indicating the area of mouse sensitivity. Labels are drawn next to the dots (see link::#-setString::). This style always draws nodes with emphasis::equal width and height::, and will use the smaller of the node's sizes, if different (it never draws ellipses).
|
|
|
|
## strong::'rects':: - nodes are drawn as rounded rectangles. Labels are drawn within the bounds of the rectangles.
|
|
::
|
|
|
|
@section{NOTE}
|
|
For compatibility with existing code, calling any of link::#-thumbWidth::, link::#-thumbHeight::, link::#-setThumbWidth::, or link::#-setThumbHeight:: will automatically switch style to strong::'rects'::. You can still set a different style afterwards.
|
|
::
|
|
|
|
@section{argument}
|
|
|
|
One of the symbols:
|
|
@racketblock[\dots:: or ]
|
|
|
|
@racketblock[\rects::. Alternatively, an integer 0 or 1, for each style respectively.
|
|
|
|
]
|
|
@section{returns}
|
|
An integer 0 or 1.
|
|
|
|
@section{METHOD}
|
|
drawLines
|
|
Whether to draw the connections between the nodes.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
drawRects
|
|
Whether to draw the nodes
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
|
|
@section{METHOD}
|
|
gridOn
|
|
Whether to draw the grid.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
grid
|
|
The resolution of the grid.
|
|
|
|
@section{argument}
|
|
|
|
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.
|
|
|
|
@section{METHOD}
|
|
thumbWidth
|
|
Sets the width of all nodes.
|
|
|
|
@section{NOTE}
|
|
For compatibility with existing code, this will set the link::#-style:: to strong::'rects'::. ::
|
|
|
|
@section{argument}
|
|
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
thumbHeight
|
|
Sets the height of all nodes.
|
|
|
|
@section{NOTE}
|
|
For compatibility with existing code, this will set the link::#-style:: to strong::'rects'::. ::
|
|
|
|
@section{argument}
|
|
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
thumbSize
|
|
Sets both link::#-thumbWidth:: and link::#-thumbHeight:: to the argument.
|
|
|
|
@section{METHOD}
|
|
strokeColor
|
|
The color used to draw the connections and the node labels.
|
|
|
|
@section{argument}
|
|
|
|
A Color.
|
|
|
|
@section{METHOD}
|
|
fillColor
|
|
The default color used to draw the nodes. If the color of a specific node has been set using link::#-setFillColor::, it will take precedence.
|
|
|
|
@section{argument}
|
|
|
|
A Color.
|
|
|
|
@section{METHOD}
|
|
selectionColor
|
|
The color of a node when it is selected.
|
|
|
|
@section{argument}
|
|
|
|
A Color.
|
|
|
|
|
|
@section{METHOD}
|
|
gridColor
|
|
The color of the grid.
|
|
|
|
@section{argument}
|
|
|
|
A Color.
|
|
|
|
@section{METHOD}
|
|
colors
|
|
Sets the link::#-strokeColor:: and the link::#-fillColor:: to the arguments, respectively.
|
|
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Interaction
|
|
|
|
@section{METHOD}
|
|
index
|
|
The index of the emphasis::current:: node, i.e. the node affected by link::#-x:: and link::#-y:: methods.
|
|
|
|
This is the selected node with lowest index, or -1 if no selection.
|
|
|
|
@section{argument}
|
|
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
lastIndex
|
|
The last node selected, regardless of the current state of selection.
|
|
|
|
|
|
@section{METHOD}
|
|
selectIndex
|
|
Selects the node at given index and makes it the current one, i.e. link::#-currentvalue:: will relate to that node. As a special case, if the argument is -1 all nodes will be deselected.
|
|
|
|
@section{argument}
|
|
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
deselectIndex
|
|
Deselects the node at given index.
|
|
|
|
@section{note}
|
|
Not available in strong:: Cocoa GUI ::. ::
|
|
|
|
@section{argument}
|
|
|
|
An Integer.
|
|
|
|
@section{METHOD}
|
|
editable
|
|
Whether any node is editable.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
setEditable
|
|
Sets whether the node at given index is editable. Regardless of this, no node will be editable unless link::#-edi@section{table}
|
|
is
|
|
@racketblock[true::.
|
|
|
|
]
|
|
@section{argument}
|
|
index
|
|
An Integer.
|
|
|
|
@section{argument}
|
|
flag
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
step
|
|
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.
|
|
|
|
@section{argument}
|
|
|
|
A Float.
|
|
|
|
@section{METHOD}
|
|
keepHorizontalOrder
|
|
|
|
Whether the position of nodes on the horizontal axis shall be restricted by their immediate neighbours (in order of their index).
|
|
|
|
Setting this to
|
|
@racketblock[true:: will immediately modify the positions of existing nodes to match the order.
|
|
|
|
]
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
elasticSelection
|
|
|
|
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 link::#-keepHorizontalOrder:: is
|
|
@racketblock[true::, a neighbour node).
|
|
|
|
If this is ]
|
|
|
|
@racketblock[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.
|
|
|
|
]
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Actions
|
|
|
|
@section{METHOD}
|
|
action
|
|
The action object evaluated whenever the user moves a node.
|
|
|
|
@section{METHOD}
|
|
metaAction
|
|
The action object evaluated whenever the user moves a node while the Ctrl key is pressed.
|
|
|
|
@section{METHOD}
|
|
defaultKeyDownAction
|
|
|
|
Implements the default behavior on key presses.
|
|
|
|
The default behavior is defined in the C++ implementation of the view instead of this method. See link::Classes/View#Key and mouse event processing:: for explanation of how to override the behavior.
|
|
|
|
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Drag and drop
|
|
|
|
@section{METHOD}
|
|
defaultGetDrag
|
|
@section{returns}
|
|
|
|
The link::#-value::.
|
|
|
|
@section{METHOD}
|
|
defaultCanReceiveDrag
|
|
@section{returns}
|
|
|
|
True for any drag data, but the data should be in the same format as link::#-value::.
|
|
|
|
@section{METHOD}
|
|
defaultReceiveDrag
|
|
If the drag data is of the acceptable form (see link::#-defaultCanReceiveDrag:: above), sets link::#-value:: using that data.
|
|
|
|
|
|
|
|
@section{EXAMPLES}
|
|
|
|
|
|
Use as envelope view
|
|
|
|
@racketblock[
|
|
(
|
|
// use shift-click to keep a node selected
|
|
w = Window("envelope", Rect(150 , Window.screenBounds.height - 250, 250, 100)).front;
|
|
w.view.decorator = FlowLayout(w.view.bounds);
|
|
|
|
b = EnvelopeView(w, Rect(0, 0, 230, 80))
|
|
.drawLines_(true)
|
|
.selectionColor_(Color.red)
|
|
.drawRects_(true)
|
|
.resize_(5)
|
|
.step_(0.05)
|
|
.action_({arg b; [b.index, b.value].postln})
|
|
.thumbSize_(5)
|
|
.value_([[0.0, 0.1, 0.5, 1.0],[0.1,1.0,0.8,0.0]]);
|
|
w.front;
|
|
)
|
|
|
|
// show grid
|
|
b.grid = Point(0.2, 0.2);
|
|
b.gridOn_(true);
|
|
|
|
// show Env
|
|
b.setEnv(Env.asr(0.5,1, 0.2));
|
|
|
|
// make the first point unmoveable
|
|
(
|
|
b.setEditable(0,false);
|
|
)
|
|
::
|
|
|
|
Use shift click to select/unselect the points
|
|
]
|
|
|
|
@racketblock[
|
|
(
|
|
w = Window("envelope", Rect(150 , Window.screenBounds.height - 250, 400, 150)).front;
|
|
w.view.decorator = FlowLayout(w.view.bounds);
|
|
|
|
b = EnvelopeView(w, Rect(0, 0, 350, 100))
|
|
.thumbSize_(5)
|
|
.drawLines_(true)
|
|
.fillColor_(Color.green)
|
|
.selectionColor_(Color.red)
|
|
.drawRects_(true)
|
|
.value_([(0.0, 0.1 .. 1.0), (0.0, 0.1 .. 1.0)])
|
|
.setEditable(0,false);
|
|
)
|
|
|
|
(
|
|
r = Routine({
|
|
var j = 0;
|
|
20.do({ arg i;
|
|
b.selectIndex((b.size - 1).rand.abs);
|
|
0.1.wait;
|
|
b.x_(1.0.rand.abs);
|
|
b.y_(1.0.rand.abs);
|
|
});
|
|
b.selectIndex(-1);
|
|
});
|
|
AppClock.play(r);
|
|
)
|
|
::
|
|
|
|
Show boxes with a string in it:
|
|
]
|
|
|
|
@racketblock[
|
|
(
|
|
a = Window("text-boxes", Rect(200 , 450, 450, 450));
|
|
a.view.decorator = FlowLayout(a.view.bounds);
|
|
|
|
b = EnvelopeView(a, Rect(0, 0, 440, 440))
|
|
.thumbWidth_(60.0)
|
|
.thumbHeight_(15.0)
|
|
.drawLines_(true)
|
|
.drawRects_(true)
|
|
.selectionColor_(Color.red)
|
|
.value_([[0.1, 0.4, 0.5, 0.3], [0.1, 0.2, 0.9, 0.7]]);
|
|
4.do({arg i;
|
|
b.setString(i, ["this", "is", "so much", "fun"].at(i));
|
|
b.setFillColor(i,[Color.yellow, Color.white, Color.green].choose);
|
|
});
|
|
a.front;
|
|
)
|
|
|
|
(
|
|
b.connect(3, [2.0,0.0,1.0]); // the text objects can be connected
|
|
b.connect(0,[2.0,3.0,1.0]);
|
|
)
|
|
::
|
|
]
|
|
|
|
|