Enumerating and Identifying Sub-Animatables

If your plug-in wishes to support the animatable interface and appear in the track view you must identify which sub-objects are animatable. These are called sub-animatables. You can do this by overriding the following methods from the Animatable class.

Note: a parameter block is considered a single animatable sub-object, and any parameters it manages are not counted as animatable sub-objects for the purposes of the following functions.

Animatable::NumSubs() - Returns the total number of animatable sub-objects maintained by the plug-in. If a plug-in is using a parameter block to manage its parameters it should just count the parameter block as one even if it contains multiple animatable objects. By default this value returns 0.
Animatable::SubAnim() - Returns a pointer to the nth animatable sub-object. If a plug-in is using a parameter block to manage its parameters it should just return a pointer to the parameter block itself from this method. This method may return NULL so developers need to check the return value before calling other animatable sub-object methods (such as Animatable::SubAnimName()). By default this method returns NULL.
Animatable::SubAnimName() - Returns the name of the nth animatable sub-object to appear in track view. This method returns the name of the nth sub-animatable to appear in track view. A parameter block name does not show up in track view, only its sub-controllers. This is because the parameter block returns true from its override of Animatable::BypassTreeView() to tell the system to not show it in track view. This prevents the user from having to navigate another nested level to simply get to the parameters.
Animatable::SubNumToRefNum() - Used for copying and pasting in the track view. It converts an animatable index to a reference index or returns -1 if there is no correspondence. If a client does not wish an animatable to be copied or pasted then it can return -1 even if there is a corresponding reference number. By default this method returns -1.

Example 1

The following example is the implementation used by the position constraint sample:

// Return one animatable sub-objects, which correspond the parameter block
int NumSubs() {
  return 1;
}
 
// Returns the nth animatable sub-object
Animatable* SubAnim(int i) {
  return i != 0 ? pblock : NULL;
}
 
// Return the name of the nth animatable sub-object
MSTR SubAnimName(int i) {
  return GetString(IDS_AG_POSITIONPARAMS);
}
 
// Returns a reference number of the nth animatable sub-object
int SubNumToRefNum(int i) {
   if (subNum==0)
     return 0; // depends on the number and order of references
   else
     return -1;
}

Example 2

The following example demonstrates multiple sub-animatables from the simple modifier base class (SimpleMod):

int SimpleMod::NumSubs() {
  return3;
}
 
Animatable* SimpleMod::SubAnim(inti)
{
   switch (i)
   {
     case 0: return posControl; // Center
     case 1: return tmControl;  // Gizmo
     case 2: return pblock;     // Parameter block
     default: return NULL;
   }
}
 
MSTR SimpleMod::SubAnimName(inti)
{
   switch (i)
   {
     case 0: return MSTR(_M("Center"));
     case 1: return MSTR(_M("Gizmo"));
     case 2: return MSTR(_M("Parameters"));
     default: return MSTR(_M(""));
   }
}