Class ComponentCollection

A class implementing a flexible, type-based system for keeping track of components that are added to objects. A ComponentCollection can simply be added as a member of an object that needs components attached to it, then used by a list.

Inheritance

Object

ComponentCollection

GenerationContext

Implements

IComponentCollection

IEnumerable<ComponentTagPair>

IEnumerable

Namespace: GoRogue.Components

Assembly: GoRogue.dll

Syntax

public class ComponentCollection : Object, IComponentCollection, IEnumerable<ComponentTagPair>, IEnumerable

Remarks

This collection allows you to add arbitrary objects to it, optionally associated with a string tag. It then allows you to very efficiently query whether or not an object has a component of a given type and tag, and retrieve that object, in a type-safe way. It handles cases where multiple objects of a single type are added, as well as cases where inheritance and/or interfaces are involved.

While components may be of any type, thanks to value-type defensive copying it is highly recommended that you refrain from using value types as components.

You may also control the order/priority with which components are retrieved. Components are retrieved in the order they were added by default. If you would like more control than this, you may have your components implement ISortedComponent. Although implementing this interface is not required, any components that do implement it are returned before any components that do not. Similarly, components with a lower sort order are returned before those with higher sort orders.

It is worthy of note that, when given as a tag parameter, "null" is used to mean "no particular tag", rather than "no tag whatsoever"; a call to a function that retrieves components that is given a tag of "null" can retrieve any component meeting the type restrictions, regardless of whether it is associated with a tag.

Finally, if components implementing IParentAwareComponent are added/removed, their parent field will be automatically updated as needed.

Constructors

ComponentCollection(IObjectWithComponents)

Constructor.

Declaration

public ComponentCollection(IObjectWithComponents parentForAddedComponents = null)

Parameters

Type	Name	Description
IObjectWithComponents	parentForAddedComponents	Parent value to use for any IParentAwareComponent instances added to the collection. If null is specified, nothing is set to the Parent field.

ComponentCollection(IEnumerable<ComponentTagPair>)

Constructor taking a set of starting components and their associated tags.

Declaration

public ComponentCollection(IEnumerable<ComponentTagPair> objectsAndTags)

Parameters

Type	Name	Description
IEnumerable<ComponentTagPair>	objectsAndTags	Components to initially add and their corresponding tags.

ComponentCollection(IEnumerable<ComponentTagPair>, IObjectWithComponents)

Constructor taking a set of starting components and their associated tags.

Declaration

public ComponentCollection(IEnumerable<ComponentTagPair> objectsAndTags, IObjectWithComponents parentForAddedComponents)

Parameters

Type	Name	Description
IEnumerable<ComponentTagPair>	objectsAndTags	Components to initially add and their corresponding tags.
IObjectWithComponents	parentForAddedComponents	Parent value to use for any IParentAwareComponent instances added to the collection. If null is specified, nothing is set to the Parent field.

ComponentCollection(IEnumerable<Object>, IObjectWithComponents)

Constructor taking a set of starting components.

Declaration

public ComponentCollection(IEnumerable<object> objects, IObjectWithComponents parentForAddedComponents = null)

Parameters

Type	Name	Description
IEnumerable<Object>	objects	Components to initially add.
IObjectWithComponents	parentForAddedComponents	Parent value to use for any IParentAwareComponent instances added to the collection. If null is specified, nothing is set to the Parent field.

Properties

Count

Number of components attached.

Declaration

public int Count { get; }

Property Value

Type	Description
Int32

ParentForAddedComponents

Object automatically set as the parent for any IParentAwareComponent added to the collection. Useful if you have components associated with an object. This defaults to null, and if its value is null, no parent is set when components are added.

Declaration

public IObjectWithComponents ParentForAddedComponents { get; set; }

Property Value

Type	Description
IObjectWithComponents

Methods

Add<T>(T, String)

Adds the given object as a component, optionally giving it a tag. Throws ArgumentException if the given object is already in this collection.

Declaration

public void Add<T>(T component, string tag = null)
    where T : class

Parameters

Type	Name	Description
T	component	Component to add.
String	tag	An optional tag to give the component. Defaults to no tag.

Type Parameters

Name	Description
T

Clear()

Removes all components from the collection.

Declaration

public void Clear()

Contains(ComponentTypeTagPair[])

True if, for each pair specified, there exists a component of the given type with the given tag in the collection.

Declaration

public bool Contains(params ComponentTypeTagPair[] componentTypesAndTags)

Parameters

Type	Name	Description
ComponentTypeTagPair[]	componentTypesAndTags	One or more component types and corresponding tags to check for.

Returns

Type	Description
Boolean

Remarks

If "null" is specified as a tag, it indicates no particular tag; eg. any object of the given type will meet the requirement, regardless of whether or not it has a tag.

Contains(Type, String)

True if a component of the specified type, and associated with the specified tag if one is specified, has been added; false otherwise.

Declaration

public bool Contains(Type componentType, string tag = null)

Parameters

Type	Name	Description
Type	componentType	The type of component to check for.
String	tag	The tag to check for. If null is specified, no particular tag is checked for.

Returns

Type	Description
Boolean

Remarks

If "null" is specified for tag, it indicates no particular tag; eg. any object of the given type will meet the requirement, regardless of whether or not it has a tag.

Contains(Type[])

True if at least one component of each type specified has been added; false otherwise.

Declaration

public bool Contains(params Type[] componentTypes)

Parameters

Type	Name	Description
Type[]	componentTypes	One or more component types to check for.

Returns

Type	Description
Boolean

Contains<T>(String)

True if a component of the specified type, and associated with the specified tag if one is specified, has been added; false otherwise.

Declaration

public bool Contains<T>(string tag = null)
    where T : class

Parameters

Type	Name	Description
String	tag	The tag to check for. If null is specified, no particular tag is checked for.

Returns

Type	Description
Boolean

Type Parameters

Name	Description
T	Type of component to check for.

Remarks

If "null" is specified for tag, it indicates no particular tag; eg. ANY object of the given type will meet the requirement, whether that object has a tag or not.

GetAll<T>()

Gets all components of type T that have been added, with components having a lower SortOrder being returned first. Components that do not implement ISortedComponent are returned after any that do. Among components with equal sort orders or components that do not implement ISortedComponent, components are returned in the order they were added.

Declaration

public IEnumerable<T> GetAll<T>()
    where T : class

Returns

Type	Description
IEnumerable<T>

Type Parameters

Name	Description
T	Type of components to retrieve.

GetEnumerator()

Returns all components paired with their tags. Ordered with respect to sorted components.

Declaration

public IEnumerator<ComponentTagPair> GetEnumerator()

Returns

Type	Description
IEnumerator<ComponentTagPair>

GetFirst<T>(String)

Gets the component of type T in the collection that has been associated with the given tag, or the component of type T with the lowest SortOrder if no tag is specified.

Declaration

public T GetFirst<T>(string tag = null)
    where T : class

Parameters

Type	Name	Description
String	tag	Tag for component to retrieve. If null is specified, no particular tag is checked for.

Returns

Type	Description
T

Type Parameters

Name	Description
T	Type of component to retrieve.

Remarks

Among components with equal sort orders or components that do not implement ISortedComponent, the first component of the given type that was added is returned.

Throws ArgumentException if no component of the given type associated with the given tag has been added.

If "null" is specified for tag, it indicates no particular tag; eg. ANY object of the given type will meet the requirement, whether that object has a tag or not.

GetFirstOrDefault<T>(String)

Gets the component of type T in the collection that has been associated with the given tag, or the component of type T with the lowest SortOrder if no tag is specified.

Declaration

public T GetFirstOrDefault<T>(string tag = null)
    where T : class

Parameters

Type	Name	Description
String	tag	Tag for component to retrieve. If null is specified, no particular tag is checked for.

Returns

Type	Description
T

Type Parameters

Name	Description
T	Type of component to retrieve.

Remarks

Among components with equal sort orders or components that do not implement ISortedComponent, the first component of the given type that was added is returned.

Returns default(T) if no component of the given type/associated with the given tag has been added. If you would instead like to throw an exception if a component of the given type is not found, see GetFirst<T>(String).

If "null" is specified for tag, it indicates no particular tag; eg. ANY object of the given type will meet the requirement, whether that object has a tag or not.

Remove(Object)

Removes the given component from the collection. Throws ArgumentException if the component isn't in the collection.

Declaration

public void Remove(object component)

Parameters

Type	Name	Description
Object	component	Component to remove.

Remove(Object[])

Removes the given component(s) from the collection. Throws ArgumentException if a component given isn't in the collection.

Declaration

public void Remove(params object[] components)

Parameters

Type	Name	Description
Object[]	components	One or more components to remove.

Remove(String)

Removes the component with the given tag. Throws ArgumentException if a component with the specified tag does not exist.

Declaration

public void Remove(string tag)

Parameters

Type	Name	Description
String	tag	Tag for component to remove.

Remove(String[])

Removes the component(s) with the given tags. Throws ArgumentException if a tag is encountered that does not have an object associated with it.

Declaration

public void Remove(params string[] tags)

Parameters

Type	Name	Description
String[]	tags	Tag(s) of components to remove.

Events

ComponentAdded

Fired when a component is added to the collection.

Declaration

public event EventHandler<ComponentChangedEventArgs> ComponentAdded

Event Type

Type	Description
EventHandler<ComponentChangedEventArgs>

ComponentRemoved

Fired when a component is removed from the collection.

Declaration

public event EventHandler<ComponentChangedEventArgs> ComponentRemoved

Event Type

Type	Description
EventHandler<ComponentChangedEventArgs>

Implements

IComponentCollection

System.Collections.Generic.IEnumerable<T>

System.Collections.IEnumerable

Extension Methods

Utility.Yield<T>(T)