////////////////////////////////////////////////////////////////////////////////
//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////

package mx.collections
{

import flash.events.IEventDispatcher;
import mx.events.CollectionEvent;

/**
 *  Dispatched when the ICollectionView has been updated in some way.
 *
 *  @eventType mx.events.CollectionEvent.COLLECTION_CHANGE
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
[Event(name="collectionChange", type="mx.events.CollectionEvent")]

/**
 *  An <code>ICollectionView</code> is a view onto a collection of data.
 *  The view can be modified to show the data sorted according to various
 *  criteria or reduced by filters without modifying the underlying data.
 *  An IViewCursor provides to access items within a
 *  collection. You can modify the collection by using the IViewCursor
 *  interface <code>insert()</code> and <code>remove()</code> methods.
 *
 *  <p>An <code>ICollectionView</code> may be a view onto data that has been
 *  retrieved from a remote location.
 *  When Implementing this interface for data
 *  that may be remote it is important to handle the case where data
 *  may not yet be available, which is indicated by the
 *  <code>ItemPendingError</code>.</p>
 *
 *  <p>The <code>IList</code> interface is an alternative to the
 *  <code>ICollectionView</code> interface.</p>
 *
 *  @see mx.collections.IViewCursor
 *  @see mx.collections.errors.ItemPendingError
 *  @see mx.collections.IList
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
public interface ICollectionView extends IEventDispatcher
{
	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------

	//----------------------------------
	//  length
	//----------------------------------

    /**
     *  The number of items in this view.
	 *  0 means no items, while -1 means that the length is unknown.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function get length():int;

	//----------------------------------
	//  filterFunction
	//----------------------------------

    /**
     *  A function that the view will use to eliminate items that do not
     *  match the function's criteria.
	 *  A filterFunction is expected to have the following signature:
	 *
	 *  <pre>f(item:Object):Boolean</pre>
	 *
	 *  where the return value is <code>true</code> if the specified item
	 *  should remain in the view.
	 *
     *  <p>If a filter is unsupported, Flex throws an error when accessing
     *  this property.
     *  You must call <code>refresh()</code> after setting the
	 *  <code>filterFunction</code> property for the view to update.</p>
	 *
 	 *  <p>Note: The Flex implementations of ICollectionView retrieve all
	 *  items from a remote location before executing the filter function.
	 *  If you use paging, apply the filter to the remote collection before
	 *  you retrieve the data.</p>
	 *
     *  @see #refresh()
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function get filterFunction():Function;
    
	/**
	 *  @private
	 */
	function set filterFunction(value:Function):void;

	//----------------------------------
	//  sort
	//----------------------------------

    /**
     *  The ISort that will be applied to the ICollectionView.
	 *  Setting the sort does not automatically refresh the view,
	 *  so you must call the <code>refresh()</code> method
	 *  after setting this property.
     *  If sort is unsupported an error will be thrown when accessing
     *  this property.
	 *
	 *  <p>Note: The Flex implementations of ICollectionView retrieve all
	 *  items from a remote location before executing a sort.
	 *  If you use paging with a sorted list, apply the sort to the remote
	 *  collection before you retrieve the data.</p>
	 *
     *  @see #refresh()
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function get sort():ISort;
    
	/**
	 *  @private
	 */
    function set sort(value:ISort):void;

	//--------------------------------------------------------------------------
	//
	//  Methods
	//
	//--------------------------------------------------------------------------

    /**
     *  Creates a new IViewCursor that works with this view.
     *
     *  @return A new IViewCursor implementation.
     *
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function createCursor():IViewCursor;

    /**
     *  Returns whether the view contains the specified object.
	 *  Unlike the <code>IViewCursor.find<i>xxx</i></code> methods,
	 *  this search is succesful only if it finds an item that exactly
	 *  matches the parameter.
     *  If the view has a filter applied to it this method may return
	 *  <code>false</code> even if the underlying collection
	 *  does contain the item.
     *
     *  @param item The object to look for.
	 *
     *  @return true if the ICollectionView, after applying any filter,
     *  contains the item; false otherwise.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function contains(item:Object):Boolean;

    /**
     *  Prevents changes to the collection itself and items within the
	 *  collection from being dispatched by the view.
	 *  Also prevents the view from updating the positions of items
	 *  if the positions change in the collection.
	 *  The changes will be queued and dispatched appropriately
	 *  after <code>enableAutoUpdate</code> is called.
	 *  If more events than updates to a single item occur,
	 *  the view may end up resetting. 
	 *  The <code>disableAutoUpdate</code> method acts cumulatively;
	 *  the same number of calls to <code>enableAutoUpdate</code>
	 *  are required for the view to dispatch events and refresh.
	 *  Note that <code>disableAutoUpdate</code> only affects the
     *  individual view; edits may be detected on an individual
	 *  basis by other views.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function disableAutoUpdate():void;

    /**
     *  Enables auto-updating.
	 *  See <code>disableAutoUpdate</code> for more information.
	 *
     *  @see #disableAutoUpdate()
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function enableAutoUpdate():void;

    /**
     *  Notifies the view that an item has been updated.
	 *  This method is useful if the contents of the view do not implement
	 *  <code>IPropertyChangeNotifier</code>.
	 *  If the call to this method includes a <code>property</code> parameter,
	 *  the view may be able to optimize its notification mechanism.
     *  Otherwise it may choose to simply refresh the whole view.
     *
     *  @param item The item within the view that was updated.
	 *
     *  @param property The name of the property that was updated.
	 *
     *  @param oldValue The old value of that property. (If property
	 *  was null, this can be the old value of the item.).
	 *
     *  @param newValue The new value of that property. (If property
	 *  was null, there's no need to specify this as the item is assumed
	 *  to be the new value.)
     *
     *  @see mx.events.CollectionEvent
     *  @see mx.core.IPropertyChangeNotifier
     *  @see mx.events.PropertyChangeEvent
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function itemUpdated(item:Object, property:Object = null,
                         oldValue:Object = null, newValue:Object = null):void;

    /**
     *  Applies the sort and filter to the view.
	 *  The ICollectionView does not detect changes to a sort or
	 *  filter automatically, so you must call the <code>refresh()</code>
	 *  method to update the view after setting the <code>sort</code> 
	 *  or <code>filterFunction</code> property.
	 *  If your ICollectionView implementation also implements
	 *  the IMXMLObject interface, you should to call the
	 *  <code>refresh()</code> method from your <code>initialized()</code>
	 *  method.
	 *
     *  <p>Returns <code>true</code> if the refresh was successful
	 *  and <code>false</code> if the sort is not yet complete
	 *  (e.g., items are still pending).
	 *  A client of the view should wait for a CollectionEvent event
	 *  with the <code>CollectionEventKind.REFRESH</code> <code>kind</code>
	 *  property to ensure that the <code>refresh()</code> operation is
	 *  complete.</p>
     *
     *  @return <code>true</code> if the refresh() was complete,
	 *  <code>false</code> if the refresh() is incomplete.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function refresh():Boolean;
}

}