Menu Functions
The following CAL functions emulate the MENU BAR commands that are available to the
user from the drop-down lists at the top of the Cakewalk screen. I will be presenting
these functions in somewhat different format than you would see in the CAL help screens or
earlier tutorials. In those places the functions and their argument map are presented in a
rather cryptic format that only C programmers are likely to find familiar. The rest of the
world would tend to look at them and scratch their heads. To prevent this tutorial from
falling into the same abyss of non-clarity, I will be presenting the functions using
something closer to plane English.
For the
sake of background, let me mention that there are several versions for most of the EDIT
functions. First, there are the ones from Cakewalk version 3 which I will call CAL30
functions and those from Cakewalk version 4 and above, which I will call CAL40 functions.
The difference is the argument list in the CAL40 functions reflecting the
"assumption" that the "From" and "Thru" markers are set
elsewhere and so no provision is made in the argument list for them, nor for the "Use
Event Filter" yes/no check box argument. Along with this change there are a few CAL40
functions that have expanded argument lists that reflect the additional options available
in versions 5 and 6 such as the audio and clip editing features. Finely, there are some
TRACK menu functions that are new as of version 7. Version 8 doesn't appear to have
changed CAL from the version 7 implementation.
You will likely notice that, for the most part, if you know how to use the Cakewalk
drop-down MENU commands, then you can use the CAL functions. There are notable exceptions.
One is the use of the editing and interpolating filters. These can be a bit of a pain in
the butt. However, I will show you how we can use the recording
of CAL macros to generate the prototype code for setting up these filters which then
require only a bit of editing to make them usable in a program. Another is the bug that
exists in Cakewalk version 6 which prevents the EditInterpolate function from
acknowledging the "From" and "Thru" markers. Instead, the function
will operate on the entire track at once. As a side effect of this bug, after the function
runs, the values stored in the markers are dumped and replaced with the times
corresponding to the start and end points of the sequence respectively. There is a
work-around for this problem. See the section called Forcing
EditInterpolate To Use Markers on the Tips, Techniques and
Work-Arounds page for details.
One
of the most important aspects of using these MENU functions is the limitation that they
will NOT run within a "forEachEvent"
loop. This makes sense if you think about it, but I mention it here so there is no
misunderstanding as to the nature of these functions. This is the only restriction. They
work very well and are quite useful in "while"
loops and branching functions like "if".