Interface IComponentCollection

Interface for a collection of components, of arbitrary types, that can optionally be associated with an arbitrary, unique tag string. A concrete implementation is provided; see ComponentCollection.

Namespace: GoRogue.Components

Assembly: GoRogue.dll

Syntax

public interface IComponentCollection : IEnumerable<ComponentTagPair>, IEnumerable

Remarks

Typically, you will not need to implement this yourself, as ComponentCollection should be suffice for most use cases. Nonetheless, the interface is provided for completeness, or if you have a need to re-implement it for a corner case of performance.

It is worthy of note that "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.

Properties

Count

Number of components attached.

Declaration

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

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

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

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

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

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

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

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

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

Returns

Type	Description
IEnumerable<T>

Type Parameters

Name	Description
T	Type of components to retrieve.

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

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

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

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

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

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

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

event EventHandler<ComponentChangedEventArgs> ComponentAdded

Event Type

Type	Description
EventHandler<ComponentChangedEventArgs>

ComponentRemoved

Fired when a component is removed from the collection.

Declaration

event EventHandler<ComponentChangedEventArgs> ComponentRemoved

Event Type

Type	Description
EventHandler<ComponentChangedEventArgs>

Extension Methods

Utility.Yield<T>(T)