Groups of items

Group - type of item that contains a set of other items. The main parameters for group is size and position that limit child items. A group item - is common item, it might contain graphics or images or it might be empty.

Default XML description of group looks like empty item:

<cg-item id='group-000'>
    <cg-props pos-x='179' pos-y='100' show='yes' alpha='255' bg-color='Black(0)' move-type='accel-both' pixel-ar='0.' play-mode='loop' interlace='auto' scale='fit-ar' align='top-left' width='314' height='98' pause='no' edges-smooth='0'>
        <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>
</cg-item>

Character Generator makes items to combine into group by using group-id attribute in child items XML. Here is example of child item for group-000 group:

<cg-item id='text-001' group-id='graphics-000' group-eos='yes'>
 <text type='text' font='Arial' font-size='28' color='White' word-break='no'>Sample Text</text>
 <cg-props scale='text-scale' align='top-left' edges-smooth='0' pos-x='0' pos-y='0' show='yes' move-type='accel-both' alpha='255' bg-color='Black(0)' pixel-ar='0.' play-mode='loop' interlace='auto' width='251' height='46' 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>
</cg-item>

The main node <cg-item> contains additional attributes that define item behavior in group:

• group-id - ID of parent item.
• group-eos - repeat "end-of-stream" (eos) behavior of parent item. Possible values: 'yes', 'no'.

Also note that base item properties (<cg-props> node) contains <group-indent> child node. Group indent indicates how many pixels from each group borders would be indented for the item.

For example, here is group based on graphics item:

<cg-item id='graphics-000'>
    <graphics type='rect' color='red(80)/blue(180)/green(80)'/>
    <cg-props pos-x='36' pos-y='24' show='yes' move-type='accel-both' alpha='255' bg-color='Black(0)' pixel-ar='0.' play-mode='loop' interlace='auto' scale='fit-ar' align='top-left' width='251' height='140' pause='no' edges-smooth='0'>
        <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>
    <internal/>
</cg-item>

Create a group and add items

To create a new group you should add some item into group. To do it you should call GroupAddItem method. This method contains the following parameters:

• _bsItemID - item identifier that you want to add to group.
• _bAddAsReference - indicates whether the new item is reference of old item. It means that if you change something with old item then all this changes will be implement to the new one.
• _bsGroupType - type of a group. Not necessary to use at the moment - use empty string for this parameter.
• _pbsGroupID - identifier of newly created group. It is possible to use existed item ID - it will be parent item for group's content. If you use empty string - a new empty item is created and it is used as parent for group.

Here is example of how to create a new group:

string itemID = "text-000";
string newGroupID = "";
int isAddAsReference = 0;
string groupType = "";
m_objCharGen.GroupAddItem(itemID, isAddAsReference, groupType, ref newGroupID);

To add items to existed group you should use the same method but use existed item as group-id. In example above you should use result value of newGroupID to add other items to the same group.

Get items in group

XML description of group doesn't contain any information about what items are inside the group. To get items within a group you should firstly get information about how many items there is in the group with GroupItemsCount method:

string groupID = "group-000";
int groupCount;
m_objCharGen.GroupItemsCount(groupID, out groupCount);

If the result is 0 - it means that you work with common item (not group). Else you can get all the items within the group by using GroupGetItem method:

string[] groupItems;
if (groupCount > 0)
{
    groupItems = new string[groupCount];
    for (int itemIndex = 0; itemIndex < groupCount; itemIndex++)
    {
        string groupItemID;
        m_objCharGen.GroupGetItem(groupID, itemIndex, out groupItemID);
        groupItems[itemIndex] = groupItemID;
    }
}

Then you can modify any item that is inside a group.

You can also get know in what group is any item. To do it you should call GroupGetItemGroup method:

string itemId = "text-000";
string groupId;
m_objCharGen.GroupGetItemGroup(itemId, out groupId);

Remove items from group

You can remove item from group with GroupRemoveItem method. Your item is not removed from Character Generator configuration - it just becomes ungrouped.

string itemId = "text-000";
string groupId = "group-000";
m_objCharGen.GroupRemoveItem(groupId, itemId);

Ungroup items

You can ungroup all the items with GroupRemoveAll method. This method contains the following parameters:

• _bsGroupID -identifier of group
• _eRemoveType - type of removing. Possible values are listed in eCG_GroupItemsRemoveType enumeration:
  
  • eCGRT_RemoveOnlyGroup - remove only group item: all child items exist after this method's call
  • eCGRT_RemoveOnlyItems - remove only items: all child items are removed - the only parent item exist after this method's call
  • eCGRT_Ungroup - ungroup items - simple ungroup: all items (parent and child) exist after this method's call

string groupId = "group-000"; 
eCG_GroupItemsRemoveType removeType = eCG_GroupItemsRemoveType.eCGRT_Ungroup;
m_objCharGen.GroupRemoveAll(groupId, removeType);