Arguments to enved consist of a series of plot objects and keyword values. To facilitate typing plots can also be specified as coordinate lists in the form (x1 y1 x2 y2 ...). The order keyword in the argument list is important, in particular axis specifications should precede plot definitions that use them. Most keywords specificions are "sticky" so they only have to provided once for a series of plot definitions that use them.

enved supports the following keywords:

:window-title {string}

The name of the window to display in the window's title bar. Defaults to "Enved".

:window-position {point}

The xy point position for the Enved window to be placed on the screen.

:window-size {point}

The width and height of the Enved window encoded as an xy point.

:window-show {t | nil}

If true the Enved window is made visible before being returned by the function, otherwise the window is returned without appearing on the screen. The default value is to show the window.

:undo-length {integer}

The length of the undo command stack, defaults to 10.

:file {pathname}

The default name of the file to save the window to.

:object {object}

An musical object (such as a midi-note or a CLM instrument note) which Enved uses to as default information to produce sound from envelope data. Envelopes are linked to slots in the object by sharing the same name. Slots that will not be set by envelope values should already be set before passing the object to Enved.

The focus plot provides the "points" that will be heard in the sound output. Enved uses linear interpolation to prodice values from the other plots affecting the sound.

:y-axis (axis | list)

Specifies a display axis. The value can be an axis object created using make-axis, or a list suitable for passing to make-axis.

:x-axis (&key keywords)

Specifies an x-axis. See make-axis

:data-format {:xy | :x | :y | :notes | :keynums | :xzy }

Determines how plot data specified to enved should be parsed. If :data-format is :notes or :keynums then the coordinates are parsed as note names or scale degrees and the :y-axis type automatically defaults to the appropriate choice. A :data-format specification must precede plot definitions that use it in the argument list. See the discussion of make-plot for more information.

:container {object}

Specifies a container (such as a thread or algorithm) from which values will be sampled to create parametric plots of the objects in the container. The :container object is used in conjunction with one or more :slot specifications described below and must precede them in the argument list.

:slot {spec}

Specifies a slot from which to sample values to produce a plot. The slot specification can be the name (symbol) of a slot or a list in the format:

(slot &key :skip :wait &allow-other-keys)

Slot is the name (symbol) of the slot whose values will be plotted from the events of :container. For :xzy plots the slot name should be a list of two slots: (y-slot z-slot). :skip and :wait are optional keyword arguments to control the "sampling rate" of plot values. :skip specifies the number of events to skip between each sampled value and defaults to 0, which means that every slot value receives a coordinate in the plot. :wait is an optional minimum "waiting time" between sampled values, ie the next sampled value must be at least :wait seconds away from the current value. &allow-other-keys are any additional keywords to make-plot as described above.

For information on using Enved see the editor's on-line Help window.

Enved API

1. Window functions
2. Plot functions
3. Axis functions
4. Editing functions
5. Sound functions

enved (&rest args)

[Enved Function]

Creates an Enved window. See main entry for a discussion of args.

 

enved-close (window)

[Enved Function]

Closes window and removes it from *enved-windows*.

 

enved-rename (window newtitle)

[Enved Function]

Sets window's title to newtitle.

 

enved-save (window &optional file)

[Enved Function]

Saves window to file,. If file is not specified enved-save uses the value of the window's file slot or pops up a "choose file" dialog if there is no file currently associated with window.

 

enved-scroll (window axis amount)

[Enved Function]

Scrolls window according to axis and amount. Axis should be either :X or Y. Amount is a number between 0.0 and 1.0, where 0.0 means to scroll to the full left or top and 1.0 means full right or bottom.

 

*enved-windows*

[Enved Variable]

The list of active Enved windows.

 

enved-windows(&optional title)

[Enved Function]

If title is nil the most recently selected Enved window is returned, otherwise the enved window matching title is returned.

 

make-plot (type &key :name :coords :color :format :x-axis :y-axis)

[Enved Function]

Creates a plot object of class type. There are currently three plot classes defined by the system: plot, slot-plot and mix-plot. The following make-plot keywords can be specified for all plot classes:

:name {string}

The name of the plot. Defaults to "Plot-1", etc.

:coords {list}

The coordinate list of the plot. Consists of a list of zero or more x and y value pairs where the x values are in monotonically increasing order. For example, (0 0 1 50 0 100) describes three coordinates whose x values range from zero to one hundred and the y values range from zero to one.

:coord-class {class}

The class of coordinate to use in the plot whenever coordinates are added. Defaults to coord. To define a new type of coordinate the class should inherit from coord-mixin, which provides X Y Z slots. The generic functions coord-to-event and fill-coord may also be specialized for new coordinates to create sound in class specific ways.

:color {integer}

The color of the plot expressed as an MCL color integer.

:format {:xy :x :y :xzy}

Specifies the external format of the coordinate list. Used by Enved to parse and reproduce external representations of the plot coordinates. If :format is not specified, Enved does its best to figure it out bu applying some tests to the coordinate list specified in the plot. The :xy format means that both coordinates are present in the data. If the value is :y the data contains only y data. In this case the x-axis specification defaults to :position and an x coordinate is automatically generated based on the y value's ordinal position in the data. If :format is :xthe data are parsed as x coordinate data. The :xzy data format creates a "piano roll" plot in which x and z values are plotted together along the shared x-axis. The x coordinate determines the position of the point along the x axis. The z coordinate is drawn as a left-to-right bar whose length reflects the magnitude of the z value. For :xzy plots each x value in the envelope specification must be a list of x and z values: ((x1 z1) y1 (x2 z2) y2 ...)

Slots plots are plots that can affect changes in data (objects) associated with the plot or its coordinates (see fill-slots for more information about this process.) The following keywords to make-plotare available for slot plots:

:slots {y-slot | (x-slot y-slot z-slot)}

A slot or list of slots to change values in. If only one slot is provided it will be affected by y coordinate values. Otherwise slots can be a list of up to three slots in X Y Z order. To affect changes in more than one slot for a given dimension, specify a list of slots at that position. For example, a "tempo" plot whose y values will affect slots Time and Duration would be specifed as :slots '((time duration)). If :slots is not specified the value of :name will be parsed to create the slot list. For example, :name "Time, Note, Duration" would specify Time as the X slot, Note as the Y slot, and Duration as the Z slot.

:data {object}

A default object to affect changes in, acording to :slots and :mode.

:mode {:set | :scale | :increment}

Determines how slots values will be affected. :set sets slot values, :scale scales them and :increment adds to them.

 

enved-add-plot(window plot)

[Enved Function]

Adds plot to window and makes it the current focus plot.

 

enved-delete-plot (window plotref)

[Enved Function]

Deletes the plot referenced by plotref from window. plotref is described in in enved-find-plot.

 

enved-find-plot (window plotref&key :test :key)

[Enved Function]

Returns the first plot in window matching plotref. if plotref is a plot it is simply returned. If plotref is a string the first plot whose name matches the string is returned. If plotref is a number the plot at that postion in the window's plot list is returned. Otherwise each plot is matched against plotref using the functions specifed by :test and :key and the first matching plot is returned.

 

enved-focus-plot (window)

[Enved Function]

Returns the current focus plot in window.

 

enved-plots (window)

[Enved Function]

Returns all the plots in window.

 

enved-rename-plot (window plotref newname)

[Enved Function]

Renames the plot referenced by plotref in window to the string newname.

 

enved-set-focus-plot (window plotref &optional redraw)

[Enved Function]

Makes the plot references by plotref the focus plot in window. If redraw? is t (the default) the window's display is redrawn. If redraw? is :erase then the window is also erased before it is redrawn.

 

make-axis (type &key :from :to :by :ticks :zoom)

[Enved Function]

Creates an axis object. type is the type of axis to create. Its value can be a type specifier: float, integer, note, keynum, position, time or a valid axis class-name (float-axis, integer-axis, note-axis, keynum-axis, time-axis and position-axis). For additional verbosity the plural and keyword forms of the axis types are also supported: float, :float, floats, :floats, and so on. The basic axis type is :float, which displays floating point values within the specified :from and :to range. If typeis :notes then y coordinate values are interpreted as note names. If typeis :keynums then y values are interpreted as MIDI scale degrees.

make-axis supports the following keywords for all axis types:

:from {value}

The minimum axis label shown. Its value depends on the type of axis created. For note and keynum axes, the value can be either note names or key numbers. The :from value defaults to the smallest y coordinate in the envelope definitions, or to some appropriate value if no coordinates were specified. :from can also be specified as :minimum.

:to {value}

The maximum axis label drawn. Its value depends on the type of axis created. Defaults to the largest y coordinate in the envelope specifications, or to some appropriate value if no coordinates were specified. :to can also be specified as :maximum.

:by {value}

Specifies the increment value between labels displayed on the axis. Default to some approriate value, usually (to-from)/4 for numeric axes otherwise 1. :by can also be specified as :increment.

:ticks

specifies the number of graduals drawn for each label and defaults to 1. If type is :float then :decimals controls the precision of the axis display as well as the y envelope coordinates output from the editor. The default decimal precision is 2. To output integer y values from the editor choose the :integer axis type.

:zoom

Specifies the ration of the lenth of the axis to the visible size of the plot view. The default value is 1.0 which means that the entire plot is visible. A :zoom factor of 2.0 will make the plot twice as large as the visible view along the dimension of the axis.

The following keywords can be specified to :note and :keynum axes:

:scale {scale |mode }

Associates a scale or mode with the axis. If a mode is specified it is transposed to the :minimum value of the axis and the plot will contain only notes appearing in the modal set. :scale defaults to *standard-scale*.

 

axis-value (axis value)

[Generic Function]

Returns the external form of value, a number in the internal coordinate system of axis.

 

axis-coordinate-value (value axis)

[Generic Function]

Returns value scaled to the internal coordinate system of axis.

 

make-coord (&key :x :y :z :data)

[Enved Function]

Creates a coordinate. Values specified to :x :y :z must already be in the interal coordinate system of the axis. Accessors are provided to get and set coordinate values: coord-x, coord-y, coord-z and coord-data.

 

coord (x y &optional z data)

[Enved Macro]

A macro version of make-coord for less typing.

 

ccl:copy (window)	[MCL Function]
ccl:cut (window)	[MCL Function]
ccl:paste (window)	[MCL Function]
ccl:undo (window)	[MCL Function]
ccl:undo-more (window)	[MCL Function]

Enved implements specialized methods for most of the MCL editing functions.

 

enved-add-coords (window coords)

[Enved Function]

Adds the list of cooordinates in coords to the focus plot in window.

 

enved-delete-coords (window coords)

[Enved Function]

Deletes the list of cooordinates in coords from the focus plot in window.

 

enved-deselect-coords (window coords)

[Enved Function]

If coords is nil then all the currently selected coordinates are deselected. Otherwise, coords is the list of selected coordinates to deselect.

 

enved-select-coords (window coords)

[Enved Function]

If coords is t all the coordinates of the focus plot are selected. Otherwise coords should be the list of cooordinates in the focus plot to select.

 

enved-select-coords-if (window test/I>)

[Enved Function]

Maps function test over all the coordinates in the focus plot and selects each one for which the the predicate returns true. The predicate is passed one argument, the current coordinate to test.

 

coord-to-object coord plot

[Generic Function]

Returns an object associated with coord. The default methodfirst looks in the data slot of the coordinate for something to return. If there is a value it is returned, otherwise the plot's data slot is examined.

 

fill-slots object slot-plot value

[Generic Function]

Fills slots of object given a slot-plot and value. If slot-plot is the plot that is actually producing the coodinates then fill-slots passes each coordinate as value, otherwise value will be the X value of the current point and fill-slot can perform some operation (such as interpolation) with slot-plot in order to fill slot values. The default method for fill-slots either sets, scales or increments slot values of object accoring to the value of the mode slot of slot-plot.

Examples:

? (enved '(0 0 100 1) '(0 1 100 0) '(0 0 25 1 75 1 100 0)
         '(0 1 10 .25  25 .1 100 0))

? (enved '(c4 e4 g4 d5 fs3) :data-format 'notes)

? (enved :y-axis '(floats from 0.0 to 100.0)
         :data-format ':y
         (loop repeat 50 collect (random 100.0)))

? (enved '(c4 e4 g4 d5 fs3) '(fs4 gs4 bf5) :data-format ':notes :y-axis '(notes from  c3 to c6))