///
/// Copyright © 2003-2008 JetBrains s.r.o.
/// You may distribute under the terms of the GNU General Public License, as published by the Free Software Foundation, version 2 (see License.txt in the repository root folder).
///
using System;
using System.Collections;
using JetBrains.Annotations;
namespace JetBrains.Omea.OpenAPI
{
///
/// An ordered collection of resources, which can optionally
/// represent the result of a live query.
///
///
/// The liveness of a resource list depends on the method which was used
/// to obtain it. The result of a list combination (,
/// or ) is live if
/// at least one of the source lists is live.
/// When a resource list is created, in most cases it contains only
/// the query condition and not the actual list of resource IDs. Such lists
/// can be created and combined (intersected, unioned and so on) with other
/// resource lists very cheapy. The resource list is instantiated (the actual
/// query is performed) only when the resources themselves (or the count of resources)
/// are accessed.
/// The resource list stores only resource IDs, not resources themselves.
/// Resources are loaded when they are actually accessed.
/// Resources in the resource list are unique - that is, the resource list
/// can contain each resource only once.
///
public interface IResourceList: IDisposable, IEnumerable
{
///
/// The total number of resources in the list.
///
///
/// Checks if a list is empty.
///
/// IResourceList list = …
///
/// if( list.Count == 0 )
/// Trace.WriteLine( "The list is empty." );
/// else
/// Trace.WriteLine( "There are resources in the list." );
///
/// Enumerates resources in the list using a for loop.
///
/// IResourceList list = …
///
/// for( int a = 0; a < list.Count; a++ )
/// Trace.WriteLine( list[a].DisplayName );
///
///
int Count { get; }
///
/// Returns the resource at the specified position in the list.
///
///
/// Enumerates resources in the list using a for loop.
///
/// IResourceList list = …
///
/// for( int a = 0; a < list.Count; a++ )
/// Trace.WriteLine( list[a].DisplayName );
///
///
IResource this[ int index ] { get; }
///
/// Provides direct access to the IDs of resources stored in the list.
///
///
/// Prints out IDs of resources in the list.
///
/// IResourceList list = …
///
/// foreach( int id in list.ResourceIds )
/// Trace.WriteLine( id );
///
///
IResourceIdCollection ResourceIds { get; }
///
/// Returns the index of the specified resource in the list.
///
/// The resource to locate.
/// The index (0-based) of the resource in the list, or -1 if the resource
/// is not found.
///
///
/// IResourceList list = …
///
/// Debug.Assert( list.IndexOf( list[0] ) == 0 ); // The first element has the 0 index
///
///
int IndexOf( IResource res );
///
/// Returns the index of the resource with the specified ID in the list.
///
/// The resource ID to locate.
/// The index (0-based) of the resource in the list, or -1 if the resource
/// is not found.
///
///
/// IResourceList list = …
///
/// int id = list[0].Id; // ID of the first element
/// Debug.Assert( list.IndexOf(id) == 0 ); // The first element is returned from this ID
///
///
int IndexOf( int resId );
///
/// Checks if the specified resource is present in the list.
///
/// The resource to locate.
/// true if the resource is present in the list, false otherwise.
/// This method matches the resource against the predicate (query condition)
/// of the list; thus, its execution time does not depend on the size of the list but
/// does depend on the query complexity.
///
/// Checks whether a resource is contained in the resource list.
///
/// IResourceList list = …
/// IResource res = …
///
/// if( list.Contains( res ) )
/// Trace.WriteLine( "Present." );
/// else
/// Trace.WriteLine( "Absent." );
///
///
bool Contains( IResource res );
///
/// A space-separated list of properties that serve as sorting keys for this resource list, or an empty string if the list is not sorted.
///
///
/// should be used instead.
/// The value consists of property names
/// separated by spaces. In addition to the registered property names, the following
/// special property names can be used: Type (equal to the resource type
/// name), ID (equal to the resource ID) and DisplayName
/// (equal to the resource display name). Each property name can be followed by a
/// - sign, which reverses the direction of sorting by that property.
/// The properties are processed in order: if the values of the first sort
/// property are equal, the values of the second sort property are compared.
///
[Obsolete] string SortProps { get; }
///
/// An array of IDs of properties that serve as sorting keys for this resource list.
///
///
/// should be used instead.
/// The first array item is the most significant one as it represents the primary sorting key.
/// To determine the sort order, use or .
///
[Obsolete] int[] SortPropIDs { get; }
///
/// Information about the sort order, either ascending (1) or descending (-1), for each sorting key. To get a corresponding property id/name, use or .
///
///
/// should be used instead.
/// Each array item is either 1 for ascending or -1 for descending sort order.
/// The first array item is the most significant one as it corresponds to the primary sorting key. If you are interested in this value only, use .
///
[Obsolete] int[] SortDirections { get; }
///
/// The sort order for the primary sorting key.
///
/// should be used instead.
/// Provides a shortcut to the first item of the array.
[Obsolete] bool SortAscending { get; }
///
/// Returns the sort settings for the resource list, or null if the resource list is not sorted.
///
/// 2.0
SortSettings SortSettings { get; }
///
/// Returns the union of the current list with another list.
///
/// The list with which the current list is unioned, or null.
/// A new resource list which is the union of the current list and the list.
///
/// may be null; in this case, the original list is returned.
/// Note that neither of the lists taking part in the union is modified and you should explicitly assign the union result to a new list. The result of one.Union( another ) will not be put in the one list, instead, it will be dropped because the return value is not utilized. You should use either the res = one.Union( another ) form, or, possibly, one = one.Union( another ) if you wish to reuse the variable. However, in the latter case you should consider taking on another overload of this function, , passing True as its second parameter, to allow the resources be actually merged into existing one resource list object. Otherwise, a new object instance will be created and then assigned to one on return, which will drop the performance.
/// The sorting order for the union result is determined as follows:
///
/// - If one of the lists participating in the union is sorted and the other is not, then the sorting will be propagated to the union product.
/// - If both lists have the same sorting then the product is sorted accordingly.
/// - If neither of the lists is sorted, the sorting of the product is undefined.
/// - If both lists are sorted and their sortings disagree, the union product sorting is undefined.
///
///
///
///
/// IResourceList listMailSentToMe = … // Acquire mail that was sent to me (personally)
/// IResourceList listMailFromMe = … // Acquire mail that was sent by me
///
/// // Make a list of all my mail
/// IResourceList listMyMail = listMailSentToMe.Union( listMailFromMe );
///
/// Note that neither listMailSentToMe nor listMailFromMe resource lists are changed in the above sample. If you do not intend to use them afterwards, consider using with the second parameter set to True instead to optimize performance.
///
IResourceList Union( IResourceList other );
///
/// Returns the union of the current list with another list, optionally reusing
/// one of the source lists.
///
/// The list with which the current list is unioned, or null.
/// If true, and if the current list or
/// is already a union, does not create a new list, but
/// instead adds the new list to the union condition of the existing union list.
/// The union of the current list and the list.
///
/// If a union of multiple lists is calculated, and the intermediate lists
/// are not used by themselves, setting to True improves
/// the performance of instantiating and maintaining the list. If its value is False, this overload behaves exactly the same way as a one-parameter .
/// may be null; in this case, the original list
/// is returned.
/// The sorting order for the union result is determined as follows:
///
/// - If one of the lists participating in the union is sorted and the other is not, then the sorting will be propagated to the union product.
/// - If both lists have the same sorting then the product is sorted accordingly.
/// - If neither of the lists is sorted, the sorting of the product is undefined.
/// - If both lists are sorted and their sortings disagree, the union product sorting is undefined.
///
///
///
/// Collect resources from multiple resource lists in a single list, reusing its object.
///
/// // Some source lists
/// IResourceList list1, list2, list3, list4, list5, …
///
/// // Collect all their items here
/// IResourceList collection;
///
/// // Add the first list
/// collection = list1;
///
/// // Add the second list (do not reuse now because this will affect the list1
/// // which we do not want to happen)
/// collection = collection.Union( list2, false );
///
/// // Now we have a brand new resource list created for the collection object
/// // and we may overwrite it freely
/// // Add the remaining lists
/// collection.Union( list3, true );
/// collection.Union( list4, true );
/// collection.Union( list5, true );
/// … // Go on for all the lists
///
///
IResourceList Union( IResourceList other, bool allowMerge );
///
/// Returns the intersection of the current list with another list.
///
/// The list with which the current list is intersected, or null.
/// A new resource list which is the intersection of the current list and
/// the list.
///
/// may be null; in this case, the original list
/// is returned.
/// Note that neither of the lists taking part in the intersection is modified and you should explicitly assign the intersection result to a new list. The result of one.Intersect( another ) will not be put in the one list, instead, it will be dropped because the return value is not utilized. You should use either the res = one.Intersect( another ) form, or, possibly, one = one.Intersect( another ) if you wish to reuse the variable. However, in the latter case you should consider taking on another overload of this function, , passing True as its second parameter, to allow the resources be actually merged into existing one resource list object. Otherwise, a new object instance will be created and then assigned to one on return, which will drop the performance.
/// The sorting order for the intersection result is determined as follows:
///
/// - If one of the lists participating in the intersection is sorted and the other is not, then the sorting will be propagated to the intersection product.
/// - If both lists have the same sorting then the product is sorted accordingly.
/// - If neither of the lists is sorted, the sorting of the product is undefined.
/// - If both lists are sorted and their sortings disagree, the intersection product sorting is undefined.
///
///
///
///
/// IResourceList annotated = … // Acquire the annotated items
/// IResourceList flagged = … // Acquire the flagged items
///
/// // Make a list of items that are both flagged and annotated
/// IResourceList both = annotated.Intersect( flagged );
///
/// Note that neither annotated nor flagged resource lists are changed in the above sample. If you do not intend to use them afterwards, consider using with the second parameter set to True instead to optimize performance.
///
IResourceList Intersect( IResourceList other );
///
/// Returns the intersection of the current list with another list, optionally reusing
/// one of the source lists.
///
/// The list with which the current list is intersected, or null.
/// If true, and if the current list or
/// is already an intersection, does not create a new list, but
/// instead adds the new list to the intersect condition of the existing intersection list.
/// The intersection of the current list and the list.
///
/// If an intersection of multiple lists is calculated, and the intermediate lists
/// are not used by themselves, setting to True improves
/// the performance of instantiating and maintaining the list. If its value is False, this overload behaves exactly the same way as a one-parameter .
/// may be null; in this case, the original list
/// is returned.
/// The sorting order for the intersection result is determined as follows:
///
/// - If one of the lists participating in the intersection is sorted and the other is not, then the sorting will be propagated to the intersection product.
/// - If both lists have the same sorting then the product is sorted accordingly.
/// - If neither of the lists is sorted, the sorting of the product is undefined.
/// - If both lists are sorted and their sortings disagree, the intersection product sorting is undefined.
///
///
///
/// Collect in a single list the resources that are common for several resource lists, reusing the target object.
///
/// // Some source lists
/// IResourceList list1, list2, list3, list4, list5, …
///
/// // Collect the items that are common for them, here
/// IResourceList commons;
///
/// // Take the first list
/// commons = list1;
///
/// // Intersect with the second list (do not reuse now because this will affect the list1
/// // which we do not want to happen)
/// commons = commons.Intersect( list2, false );
///
/// // Now we have a brand new resource list created for the commons object
/// // and we may overwrite it freely
/// // Intersect with the remaining lists
/// commons.Intersect( list3, true );
/// commons.Intersect( list4, true );
/// commons.Intersect( list5, true );
/// … // Go on for all the lists
///
///
IResourceList Intersect( IResourceList other, bool allowMerge );
///
/// Returns the difference of the current resource list and another resource list.
///
/// The resource list which is subtracted, or null.
/// A new resource list which is the difference of this and .
///
/// The returned lists contains all resources which are contained in the
/// current list but not in the list.
/// may be null; in this case, the original list
/// is returned.
/// The sorting order of the new list is undefined.
///
///
/// Collect all the items that are flagged, but not annotated.
///
/// IResourceList annotated = … // Acquire the annotated items
/// IResourceList flagged = … // Acquire the flagged items
///
/// // Produce the list of flagged-but-not-annotated items
/// IResourceList diff = flagged.Minus( annotated );
///
/// Note that neither annotated nor flagged resource lists are changed in the above sample.
///
IResourceList Minus( IResourceList other );
///
/// Checks if any of the resources in the list has the property with the specified name,
/// or if the property is provided by one of the virtual property providers attached
/// to the list.
///
/// Name of the property to check.
/// true if at least one resource has the property, false otherwise.
bool HasProp( string propName );
///
/// Checks if any of the resources in the list has the property with the specified ID,
/// or if the property is provided by one of the virtual property providers attached
/// to the list.
///
/// ID of the property to check.
/// true if at least one resource has the property, false otherwise.
bool HasProp( int propId );
///
/// Checks if all resources in the resource list are of the same type.
///
/// The type that is checked.
/// true if all the resources have the type , false otherwise.
bool AllResourcesOfType( string type );
///
/// Returns the array of all distinct resource types encountered in the resource list, arranged in lexicographical order.
///
/// The sorted array of resource type names.
string[] GetAllTypes();
///
/// Attaches a virtual property provider to the resource list.
///
/// The provider to attach.
/// Multiple providers can be attached to the resource list, providing
/// values for different virtual properties.
void AttachPropertyProvider( IPropertyProvider provider );
///
/// Returns the text of the property with the specified name for the resource
/// at the specified index of the list.
///
/// The index of the resource for which the property text
/// is requested.
/// The name of the property which is requested.
/// The value of the property.
/// If the resource has the property, it returns the actual property
/// value. If it does not, the virtual property providers attached to the list
/// are requested to provide the value.
string GetPropText( int index, string propName );
///
/// Returns the text of the property with the specified ID for the resource
/// at the specified index of the list.
///
/// The index of the resource for which the property text
/// is requested.
/// The ID of the property which is requested.
/// The value of the property.
/// If the resource has the property, it returns the actual property
/// value. If it does not, the virtual property providers attached to the list
/// are requested to provide the value.
string GetPropText( int index, int propId );
///
/// Returns the text of the property with the specified ID for the specified
/// resource in the list.
///
/// The resource for which the property text is requested.
/// The ID of the property which is requested.
/// The value of the property.
/// If the resource has the property, it returns the actual property
/// value. If it does not, the virtual property providers attached to the list
/// are requested to provide the value.
/// 2.0
string GetPropText( IResource res, int propId );
///
/// Checks if the resource at the specified index of the list has the property
/// with the specified name.
///
/// The index of the resource.
/// The name of the property which is checked.
/// true if the resource has the property, false otherwise.
/// The method returns true if either the resource actually has the
/// property or a value can be provided by a virtual property provider.
bool HasProp( int index, string propName );
///
/// Checks if the resource at the specified index of the list has the property
/// with the specified ID.
///
/// The index of the resource.
/// The name of the property which is checked.
/// true if the resource has the property, false otherwise.
/// The method returns true if either the resource actually has the
/// property or a value can be provided by a virtual property provider.
bool HasProp( int index, int propId );
///
/// Checks if the specified resource in the list has the property with the specified ID.
///
/// The resource.
/// The name of the property which is checked.
/// true if the resource has the property, false otherwise.
/// The method returns true if either the resource actually has the
/// property or a value can be provided by a virtual property provider.
/// 2.0
bool HasProp( IResource res, int propId );
///
/// Sorts the list with the specified sort settings.
///
/// The settings for sorting the resource list.
void Sort( SortSettings sortSettings );
///
/// Sorts the list by the values of the specified properties.
///
/// The string specifying the names of the properties
/// by which the list is sorted.
///
/// should be used instead.
/// The string consists of property names
/// separated by spaces. In addition to the registered property names, the following
/// special property names can be used: Type (equal to the resource type
/// name), ID (equal to the resource ID) and DisplayName
/// (equal to the resource display name). Each property name can be followed by a
/// - sign, which reverses the direction of sorting by that property.
/// The properties are processed in order: if the values of the first sort
/// property are equal, the values of the second sort property are compared.
///
[Obsolete] void Sort( string propNames );
///
/// Sorts the list by the values of the specified properties in either ascending or descending
/// direction.
///
/// The string specifying the names of the properties
/// by which the list is sorted.
/// true if the list should be sorted in ascending direction
/// (A to Z), false otherwise.
///
/// should be used instead.
/// The string consists of property names
/// separated by spaces. In addition to the registered property names, the following
/// special property names can be used: Type (equal to the resource type
/// name), ID (equal to the resource ID) and DisplayName
/// (equal to the resource display name). Each property name can be followed by a
/// - sign, which reverses the direction of sorting by that property.
/// The properties are processed in order: if the values of the first sort
/// property are equal, the values of the second sort property are compared.
///
[Obsolete] void Sort( string propNames, bool ascending );
///
/// Sorts the list by the value of the properties with the specified IDs.
///
/// Array of the IDs of properties by which the list is sorted.
/// true if the sort direction used for all properties
/// is ascending (A to Z), false if the direction is descending (Z to A).
/// The array of property IDs may contain IDs of special properties,
/// as defined in the class.
/// The properties are processed in order: if the values of the first sort
/// property are equal, the values of the second sort property are compared.
///
void Sort( int[] propIds, bool ascending );
///
/// Sorts the list by the value of the properties with the specified IDs, in
/// either ordered or equivalent mode.
///
/// Array of the IDs of properties by which the list is sorted.
/// true if the sort direction used for all properties
/// is ascending (A to Z), false if the direction is descending (Z to A).
/// If false, properties are compared in order.
/// If true, the value of the first found non-null property is used for comparing
/// every resource.
/// The array of property IDs may contain IDs of special properties,
/// as defined in the class.
/// If is false, the properties are
/// processed in order: if the values of the first sort property are equal, the
/// values of the second sort property are compared.
/// If is true, the properties are
/// considered equivalent. For every resource, the array of properties is scanned
/// until one property is found for which a resource has a non-null value. Then that
/// value is compared with a single value which is found in the same way for
/// another resource.
///
void Sort( int[] propIds, bool ascending, bool propsEquivalent );
///
/// Sorts the list by the value of the properties with the specified IDs, with
/// a direction specified for each property.
///
/// Array of the IDs of properties by which the list is sorted.
/// The sort direction which is used for comparing the values
/// of each property. If true, the sort direction used for the property
/// is ascending (A to Z), if false - the direction is descending (Z to A).
/// The array of property IDs may contain IDs of special properties,
/// as defined in the class.
/// The properties are processed in order: if the values of the first sort
/// property are equal, the values of the second sort property are compared.
///
void Sort( int[] propIds, bool[] sortDirections );
///
/// Sorts the list with the specified custom comparer.
///
/// The comparer which is used for comparing resources.
/// If true, the sort direction is ascending. If false,
/// the direction is descending (comparison values returned by the comparer are inverted).
void Sort( IResourceComparer customComparer, bool ascending );
///
/// Deletes all the resources in the resource list from the resource store.
///
void DeleteAll();
///
/// Tells that the client of the resource list wants to receive notifications
/// on the change of the specified property. If there are no watches set,
/// the client receives notifications about all the properties.
///
/// ID of the property to be monitored for changes.
/// By default, each property notifies the listeners on value change.
/// This functionality can be limited if the list of properties of interest is
/// specified by calling sequentially for each property.
/// After a first call, other properties but the stop sending
/// notifications. Any subsequent call to this function enables notifications for one
/// more property.
void AddPropertyWatch( int propId );
///
/// Tells that the client of the resource list wants to receive notifications
/// on the change of the specified properties. If there are no watches set,
/// the client receives notifications about all the properties.
///
/// ID of the properies to be monitored for changes.
/// By default, each property notifies the listeners on value change.
/// 2.0
void AddPropertyWatch( int[] propIds );
///
/// Disconnects the handlers of the resource list and moves it back to predicate state.
///
/// Before the resource list items are first accessed, it exists only as a predicate structure describing which resources should be requested to populate the list contents. This function provides for returning the list into this state.
void Deinstantiate();
///
/// Finds a resource matching the specified condition in the list.
///
/// The condition to check for each resource.
/// First resource matching the condition, or null if none was found.
[CanBeNull]
IResource Find(Predicate predicate);
///
/// Returns an enumerable which enumerates only existing and not deleted resources
/// in the resource list.
///
/// 2.0
IEnumerable ValidResources { get; }
///
/// Occurs when a resource is added to a live resource list.
///
event ResourceIndexEventHandler ResourceAdded;
///
/// Occurs before a resource is removed from a live resource list.
///
event ResourceIndexEventHandler ResourceDeleting;
///
/// Occurs when a resource in a live resource list is changed.
///
event ResourcePropIndexEventHandler ResourceChanged;
///
/// Occurs when a resource in a live resource list is removed from the list because
/// a change in its properties caused it to no longer match the list conditions.
///
/// 2.0
/// This event is fired after the regular event.
event ResourcePropIndexEventHandler ChangedResourceDeleting;
}
///
/// Defines the interface for the provider of "virtual" properties for a resource list.
///
/// "Virtual" properties are properties that are not actually present on
/// resources in the list but can be displayed in the resource browser. Examples
/// of such properties are search rank and similarity.
public interface IPropertyProvider
{
///
/// Checks if the provider can provide the values for the specified property ID.
///
/// ID of the property to check.
/// true if the provider can provide values for that property,
/// false otherwise.
bool HasProp( int propId );
///
/// Returns the value of a virtual property for a resource.
///
/// The resource for which the property value is requested.
/// The ID of the property which is requested.
/// The value of the property for the resource, or null if the value
/// cannot be provided.
object GetPropValue( IResource res, int propId );
///
/// Notifies the resource list that the value of a virtual property for a
/// specific resource has changed.
///
event PropertyProviderChangeEventHandler ResourceChanged;
}
///
/// The interface for custom comparison of resources.
///
/// Instances of this interface can be passed to
/// .
public interface IResourceComparer
{
///
/// Compares the specified two resources.
///
/// The first resource to compare.
/// The second resource to compare.
/// A negative value if is smaller than
/// ; zero if they are equal; a positive value if
/// is greater.
int CompareResources( IResource r1, IResource r2 );
}
///
/// The collection of IDs of resources stored in a resource list.
///
public interface IResourceIdCollection: ICollection
{
///
/// The ID of a resource at an index specified by .
///
int this [int index] { get; }
}
}