Compositions

Compositions are a powerful tool for easy operating a big amount of items. You can use composition for group management of items with effects for appearance and hiding.

Create new composition

You can create a new composition by adding an item to not-existing composition with the CompositionsAddItems method. This method contains the following parameters:

• _bsItemsID - ID of item that is added to composition
• _bClearBeforeAdd - indicates whether the composition is cleared before add this item ("1") or not ("0")
• _bsCompositionComment - comment to the composition. You can ignore the parameter and leave it empty ("").
• _pbsCompositionName - name of the composition. If you use a name of existed composition - the item is added to existed composition. In another case a new composition is created.

In source code, you should use something like this to add item "text-000" to new composition

string itemID = "text-000";
string compositionName = "myComposition";
int clearBeforeAdd = 0;
string compositionComment = "";
myCharGen.CompositionsAddItems(itemID, clearBeforeAdd, compositionComment, ref compositionName);

You can change a name of composition at any moment with the CompositionsChangeName method. This method contains the following parameters:

• _bsCompositionName - current composition name
• _bsNewCompositionName - new composition name
• _bsNewCommment - new composition comment

string currentCompositionName = "myComposition";
string newCompositionName = "newName";
string newComment = "newComment";
myCharGen.CompositionsChangeName(currentCompositionName, newCompositionName, newComment);

Items in composition

To add other items to existed composition you should use the CompositionsAddItems method with existed composition name.

You can get a number of items in a composition by composition ID with the CompositionsGetItemsCount method:

string compostionID = "newName";
int numberOfItems = 0;
myCharGen.CompositionsGetItemsCount(compostionID, ref numberOfItems);

Then you can get any item in the composition by item index with the CompositionsGetItem method.:

string itemID;
string itemXML;
string compostionID = "newName";
int itemIndex = 0;
m_objCharGen.CompositionsGetItem(compostionID, itemIndex, out itemID, out itemXML );

You can update existed item in composition by calling the CompositionsAddItems again for this item.

To remove an item from a composition you should use the CompositionsRemoveItem method:

string compositionID = "newName";
string itemToRemove = "text-000";
myCharGen.CompositionsRemoveItem(compositionID, itemToRemove);

Display composition

Before displaying a composition, make sure that you have loaded it into Character Generator or you have created a new one. 

To display your composition you should use the CompositionsDisplay method. This method contains the following parameters:

• _bsCompositionName - composition identifier
• _bsParamString - parameters for display. This property is reserved for future usage so you can just leave it as an empty string ("").
• _dblTimeIntro - time to introduce a composition - to show composition immediately set 0. Value is in seconds.
• _dblShowTime - time to show composition - if you want to keep a composition on screen without time limits set 0. Value is in seconds.
• _dblTimeExit - time to hide a composition - to hide it immediately set 0. Value is in seconds.

string myCompositionID = "composition-000";
string myParameters = "";
double inTime = 0.5;
double showTime = 5.0;
double hideTime = 1.5;
myCharGen.CompositionsDisplay(myCompositionID, myParameters, inTime, showTime, hideTime);

If you want to hide a composition but don't want to wait for composition timer you can call CompositionsDisplay method with negative inTime parameter:

// To hide composition immediately
myCharGen.CompositionsDisplay(myCompositionID, myParameters, -0.01, 0, 0);

Save and load composition

Compositions have XML structure where all the items of a composition are contained. The simplest XML configuration of composition looks like:

<cg-composition name='mynewcomposition' comment=''>
 <video-output background='Black(255)' top-video='no'>
  <input-rect left='0.000%' right='0.000%' top='0.000%' bottom='0.000%'/>
  <output-rect left='0.000%' right='0.000%' top='0.000%' bottom='0.000%'/>
 </video-output>
 <cg-items>
  <cg-item id='text-000' pos-x='0.10' pos-y='0' size-x='0.06' size-y='0.02'>
   <text>Sample Text</text>
   <cg-props scale='text-scale' align='top-left' edges-smooth='3' pos-x='202' pos-y='58' show='yes' move-type='accel-both' alpha='255' bg-color='Black(0)' pixel-ar='0.' play-mode='loop' interlace='auto' width='132' height='27' pause='no'>
    <indent left='0' right='0' top='0' bottom='0' use-for-bg='no'/>
    <group-indent left='0' right='0' top='0' bottom='0'/>
   </cg-props>
   <movement speed-x='1.' speed-y='0.'/>
  </cg-item>
 </cg-items>
</cg-composition>

The root node contains name of composition and a comment. There are 2 child node - video-output, that is not used anymore and cg-items, where all items of the composition are listed with all configuration. So you can edit XML of your composition to make changes for its items.

You can save you composition into an XML-formatted string or into an XML file. To save composition to a string you should call CompositionsSaveToString method:

string compositionID = "newName";
string compositionXML;
myCharGen.CompositionsSaveToString(compositionID, out compositionXML);

And there is CompositionsSaveToFile method to save composition to file:

string compositionID = "newName";
string pathToSave = @"c:\CharGen\myComposition.ml-cgc";
myCharGen.CompositionsSaveToFile(compositionID, pathToSave);

an extension ML-CGC is used only to make files easier to find later. You can use any extension to save composition. To save all compositions that are used in Character Generator you should set compositionID to the empty string (""). In this case, result file has this structure:

<cg-compositions>
 <cg-composition name='composition-000'>
  ...composition content ...
 </cg-composition>
 <cg-composition name='composition-001'>
   ...composition content ...
 </cg-composition>
</cg-compositions>

To load composition from files or from XML strings you should use CompositionsLoadOne method. This method loads a single composition by its XML description or from file:

string pathToComposition = @"c:\CharGen\myComposition.ml-cgc";
string myLoadedCompositionID;
myCharGen.CompositionsLoadOne(pathToComposition, out myLoadedCompositionID);

If your file contains several compositions you can load them all with a single call of the CompositionsLoadAll method. This method contains the following parameters:

• _bsFileNameOrXMLDescription  path to file or XML description of compositions
• _bClearBeforeLoad - indicates whether all existing composition are cleared before loading

string pathToComposition = @"c:\CharGen\myComposition.ml-cgc";
int clearBeforeLoad = 1;
myCharGen.CompositionsLoadAll(pathToComposition, clearBeforeLoad);

Compositions management

You can get a number of compositions that are loaded into Character Generator with the CompositionsGetCount method:

int numberOfCompositions;
myCharGen.CompositionsGetCount(out numberOfCompositions);

Then you can make a loop to get all the compositions names:

int numberOfCompositions;
myCharGen.CompositionsGetCount(out numberOfCompositions);
string[] listOfCompositions;
if (numberOfCompositions > 0)
{
    listOfCompositions = new string[numberOfCompositions];
    for (int compositionIndex = 0; compositionIndex < numberOfCompositions; compositionIndex++)
    {
        string compositionName;
        string compositionComment;
        myCharGen.CompositionsGetByIndex(compositionIndex, out compositionName, out compositionComment);
        listOfCompositions[compositionIndex] = compositionName;
    }
}

To remove a composition you should use CompositionsRemove method. For example, to remove the 1st item from listOfCompositions array:

myCharGen.CompositionsRemove(listOfCompositions[0]);

Effects for items in compositions

You can specify effects for items behavior in composition appearance and hide. So while the composition is appearing and hiding the effects are implemented.

In an item's XML configuration effects are set in the root 'cg-item' node

<cg-item id='graphics-000' on-show='fade' on-hide='blur'>

There are 2 types of effects - 'on-show', that is implemented for in-time of composition, and 'on-hide' that is implemented while the composition is hiding.

Here is a list of possible effects:

Effects of each type are listed in on-show and on-hide attributes through commas:

<cg-item id='graphics-000' on-show='fade, left' on-hide='blur, squeeze'>