Interface IAbstractMarkupDataContainer

Abstract interface implemented by containers that hold data items representing localizable content. For example, the IParagraph, ISegment, ITagPair, and IOtherMarker interfaces are derived from this interface.

Inherited Members
Namespace: SdlSdl.FileTypeSupportFrameworkBilingualApi
Assembly: Sdl.FileTypeSupport.Framework.Core.dll
Syntax
public interface IAbstractMarkupDataContainer : IList<IAbstractMarkupData>, ICollection<IAbstractMarkupData>, IEnumerable<IAbstractMarkupData>, IEnumerable, ISupportsUniqueId
Remarks

Adding or inserting an item into the container automatically sets the Parent property of the item. Removing an item from a container automatically sets the parent property to null.

An item can never appear in more than one container at the same time. Attempting to add an item to a container if it is already in another container causes an exception.

If you want an equivalent item to appear in two containers, you can clone it, and insert the clone into the second container. The cloned item will then reference the same properties object(s).

Implementations of this interface may or may not be IAbstractMarkupData. ITagPair is an example of a container that is also a markup data item, and can therefore appear inside other containers. IParagraph is an example of a container that is NOT a markup data item.

The following example demonstrates how to retrieve the parent container for a container node if it is a markup data item. 

IAbstractMarkupData GetParent(IAbstractMarkupDataContainer container)
{
    IAbstractMarkupData item = container as IAbstractMarkupData;
    if (item != null)
    {
        return item.Parent;
    }
    // container is not a markup data item
    return null;
}

During content manipulation it is sometimes necessary to split a container into two parts, with the first part containing some of the items, the second containing others, and both containers referencing the same properties objects. The easiest way to accomplish this is to call Split(int).

Note that not all containers can be split (for example, IParagraph cannot be split). Before calling Split(int) you should therefore check the CanBeSplit property.

Another common operation is to move items into a different container. The easiest way to do that is to use one of the overloads of MoveAllItemsTo() or MoveItemsTo().

It is sometimes necessary to reference locations inside a container. This can be done using the Location class. You can iterate over all possible locations in a container (including locations in nested containers) using the Locations iterator.

Properties

AllSubItems

An iterator that can be used to iterate over all child items - including sub-items - in the container.

Declaration
IEnumerable<IAbstractMarkupData> AllSubItems { get; }
Property Value
Type Description
IEnumerableIAbstractMarkupData
Remarks

Container items inside the container are encountered before the actual items that they contain. Note that there is no need for the caller to loop through the content of container nodes, as these will also be automatically retrieved through this iterator.

CanBeSplit

Indicates whether it is possible to split this container into different parts by calling the Split(int) method.

Declaration
bool CanBeSplit { get; }
Property Value
Type Description
bool

Locations

Iterator for all possible locations in the collection and its sub-collections

Declaration
IEnumerable<Location> Locations { get; }
Property Value
Type Description
IEnumerableLocation
Examples

Below you find an example of how you can use this iterator:

void ProcessAllText(IAbstractMarkupDataContainer container)
{
  foreach (Location location in container.Locations)
  {
    IText text = location.ItemAtLocation as IText;
    if (text != null)
    {
      ProcessText(text);
    }
  }
}

Methods

Find(Location, Predicate<Location>)

Returns the first location that matches the specified predecate, starting at a specific location.

Declaration
Location Find(Location startAt, Predicate<Location> match)
Parameters
Type Name Description
Location startAt

The location at which the search is started. This must NOT be null.

If the predicate matches this location, it will be returned.

If no corresponding location is found, null is returned.
PredicateLocation match

The predicate to evaluate for each location.
Returns
Type Description
Location

Find(Predicate<IAbstractMarkupData>)

Returns the first item that matches the specified predecate.

The iteration is performed over all items and sub-items in this collection and all sub-collections until the item is located.

Declaration
IAbstractMarkupData Find(Predicate<IAbstractMarkupData> match)
Parameters
Type Name Description
PredicateIAbstractMarkupData match

Delegate that returns true when a matching item has been found
Returns
Type Description
IAbstractMarkupData

The first item that matches the specified predicate

If no corresponding item is found, null is returned.
Examples

The following example shows how this can be used (with an anonymous method) to find the an equivalent item inside a paragraph.

IAbstractMarkupData GetEquivalentItem(IAbstractMarkupData equalItem, IParagraph para)
{
  return para.Find( 
    delegate(IAbstractMarkupData item)
    {
      return equalItem.Equals(item);
    });
}

Find(Predicate<Location>)

Returns the first location that matches the specified predecate. The iteration is performed over all locations in this collection and all sub-collections until the element is located.

Declaration
Location Find(Predicate<Location> match)
Parameters
Type Name Description
PredicateLocation match

Delegate that returns true when a matching location has been found
Returns
Type Description
Location

The first location that matches the specified predicate

If no corresponding location is found, null is returned.
Examples

This example shows how this can be used to find the location of an equivalent item inside a paragraph.

Location GetEquivalentItemLocation(IAbstractMarkupData equalItem, IParagraph para)
{
  return para.Find( 
    delegate(Location location)
    {
      return equalItem.Equals(location.ItemAtLocation);
    });
}

ForEachSubItem(Action<IAbstractMarkupData>)

Execute the specified action on each item and (recursively) each sub-item in this container.

Declaration
void ForEachSubItem(Action<IAbstractMarkupData> action)
Parameters
Type Name Description
ActionIAbstractMarkupData action
Remarks

The action is executed on the container nodes themselves before it is executed on the content items of the containers.

GetLocationsFrom(Location)

Enumerator for locations starting from a specific location

Declaration
IEnumerable<Location> GetLocationsFrom(Location startingFrom)
Parameters
Type Name Description
Location startingFrom

Must be a location inside this collection
Returns
Type Description
IEnumerableLocation

Iterator that can be used to iterate over the remainder of the collection

MoveAllItemsTo(IAbstractMarkupDataContainer)

Moves all items from this container into another one.

Declaration
void MoveAllItemsTo(IAbstractMarkupDataContainer destinationContainer)
Parameters
Type Name Description
IAbstractMarkupDataContainer destinationContainer

The container that will receive all items from this container.
Remarks

The items are added at the end of the other container, while the order is preserved.

MoveAllItemsTo(IAbstractMarkupDataContainer, int)

Moves all items from this container to a specific location in another container.

Declaration
void MoveAllItemsTo(IAbstractMarkupDataContainer destinationContainer, int insertAtIndex)
Parameters
Type Name Description
IAbstractMarkupDataContainer destinationContainer

The container that will receive all items from this container
int insertAtIndex

The index in the destination container where items should be inserted. Must be less than or equal to the number of items in the destination container.
Remarks

The order of the moved items is preserved.

MoveItemsTo(IAbstractMarkupDataContainer, int, int)

Moves a number of items from this container into another one.

Declaration
void MoveItemsTo(IAbstractMarkupDataContainer destinationContainer, int startIndex, int count)
Parameters
Type Name Description
IAbstractMarkupDataContainer destinationContainer

The container into which the items will be moved
int startIndex

Index of the first item in this container to be moved
int count

Number of items to be moved
Remarks

The items are added to the end of the container, while the order is preserved.

MoveItemsTo(IAbstractMarkupDataContainer, int, int, int)

Moves a number of items from this container into a specific location in another one.

Declaration
void MoveItemsTo(IAbstractMarkupDataContainer destinationContainer, int destinationIndex, int startIndex, int count)
Parameters
Type Name Description
IAbstractMarkupDataContainer destinationContainer

The container into which the items will be moved
int destinationIndex

The location where the items should be inserted in the destination container
int startIndex

Index of the first item in this container to be moved.
int count

Number of items to be moved
Remarks

The order of the moved items is preserved.

Split(int)

Splits this container in two. After the split, this object will hold all items with index lower than the splitBeforeItemIndex parameter. The returned object is a clone of this object, which contains all other items.

Declaration
IAbstractMarkupDataContainer Split(int splitBeforeItemIndex)
Parameters
Type Name Description
int splitBeforeItemIndex
Returns
Type Description
IAbstractMarkupDataContainer
Remarks

Note that if this item is a markup data item that is part of a parent container it will remain in that container. The returned item is not automatically inserted into the parent container. If you need it to be there, you must insert it manually.

Exceptions
Type Condition
NotSplittableException

Thrown if the collection cannot be split at the specified location.