////////////////////////////////////////////////////////////////////////////////
//
//  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.automation
{

import flash.display.DisplayObject;
import flash.events.Event;
import flash.events.IEventDispatcher;

import mx.automation.events.AutomationRecordEvent;
import mx.automation.events.AutomationReplayEvent;

/**
 *  The IAutomationManager interface defines the interface expected 
 *  from an AutomationManager object by the automation module.
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
public interface IAutomationManager 
        extends IEventDispatcher
{
    /**
     *  Returns the next parent that is visible within the automation hierarchy.
     *
     *  @param obj Automation object.
     *
     *  @param parentToStopAt Parent of the given automation object.
     *
     *  @param ignoreShowInHierarchy Boolean that determines whether object is ignored 
     *  within the automation hierarchy. The default value is <code>false</code>.    
     *
     *  @return Nearest parent of the object visible within the automation 
     *          hierarchy.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getParent(obj:IAutomationObject, 
                       parentToStopAt:IAutomationObject = null,
                       ignoreShowInHierarchy:Boolean = false):IAutomationObject;
        
    /**
     *  Returns all children of this object that are visible within the testing
     *  hierarchy and meet the criteria in the automation part.  
     *  If a child is not visible within the hierarchy, this method
     *  returns the children of the invisible child.
     *  
     *  @param obj Object for which to get the children.
     * 
     *  @param part Criteria of which children to return.
     * 
     *  @param ignoreShowInHierarchy Boolean that determines whether object is ignored 
     *  within the automation hierarchy. The default value is <code>false</code>.    
     *
     *  @return Array of children matching the criteria.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getChildrenFromIDPart(obj:IAutomationObject,
                                   part:AutomationIDPart = null,
                                   ignoreShowInHierarchy:Boolean = false):Array;

    /**
     *  Returns all children of this object that are visible within the testing
     *  hierarchy. If a child is not visible within the hierarchy, 
     *  returns the children of the invisible child.
     *  
     *  @param obj Object for which to get the children.
     *
     *  @param ignoreShowInHierarchy
     * 
     *  @param ignoreShowInHierarchy Boolean that determines whether object is ignored 
     *  within the automation hierarchy. The default value is <code>false</code>.    
     *
     *  @return Array of children.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getChildren(obj:IAutomationObject,
                         ignoreShowInHierarchy:Boolean = false):Array;
    
    /**
     *  Returns the text to display as the description for the object.
     *  
     *  @param obj Automation object.
     * 
     *  @return Text description of the Automation object.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getAutomationName(obj:IAutomationObject):String;

    /**
     *  Returns the text to display as the type of the object.
     *
     *  @param obj Automation object.
     * 
     *  @return Type of the object.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getAutomationClassName(obj:IAutomationObject):String;

    /**
     *  Returns the values for a set of properties.
     *
     *  @param obj Object for which to get the properties.
     * 
     *  @param names Names of the properties to evaluate on the object.
     * 
     *  @param forVerification If <code>true</code>, only include verification properties.
     * 
     *  @param forDescription If <code>true</code>, only include description properties.
     * 
     *  @return Array of objects that contain each property value and descriptor.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getProperties(obj:IAutomationObject, 
                           names:Array = null, 
                           forVerification:Boolean = true, 
                           forDescription:Boolean = true):Array;
    
    /**
     * Returns the object implementing the IAutomationTabularData interface through which
     * the tabular data can be obtained.
     *
     *  @param obj An IAutomationObject.
     * 
     *  @return An object implementing the IAutomationTabularData interface. 
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getTabularData(obj:IAutomationObject):IAutomationTabularData;

    /**
     *  Indicates whether recording is taking place.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function get recording():Boolean;

    /**
     *  Indicates whether replay is taking place.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function get replaying():Boolean;

    /**
     *  Sets the automation manager to record mode.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function beginRecording():void;

    /**
     *  Takes the automation manager out of record mode.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function endRecording():void;

    /**
     *  Returns the automation object under the given coordinate.
     *
     *  @param x The x coordinate.
     * 
     *  @param y The y coordinate.
     * 
     *  @return Automation object at that point.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */    
    function getElementFromPoint(x:int, y:int):IAutomationObject;

    /**
     *  The display rectangle enclosing the DisplayObject.
     *
     *  @param obj DisplayObject whose rectangle is desired.
     *
     *  @return An array of four integers: top, left, width and height.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function getRectangle(obj:DisplayObject):Array;

    /**
     *  Returns <code>true</code> if an object and all of its parents are visible.
     *  
     *  @param obj DisplayObject.
     *
     *  @return <code>true</code> if an object and all of its parents are visible.
     * 
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function isVisible(obj:DisplayObject):Boolean;

    /**
     *  Resolves an id to an automation object.
     *
     *  @param rid Automation id of the automation object.
     *
     *  @param currentParent Current parent of the automation object.
     * 
     *  @return IAutomationObject which matches with the <code>rid</code>. 
     *  If no object 
     *  is found or multiple objects are found, this method throws an exception.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function resolveIDToSingleObject(rid:AutomationID, 
                                     currentParent:IAutomationObject = null):IAutomationObject;

    /**
     *  Resolves an id to automation objects.
     *  
     *  @param rid Automation id of the automation object.
     *
     *  @param currentParent Current parent of the automation object.
     * 
     *  @return An Array containing all the objects matching the <code>rid</code>.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function resolveID(rid:AutomationID, 
                       currentParent:IAutomationObject = null):Array;
            
    /**
     *  Resolves an id part to an automation object within the parent.
     *
     *  @param parent Parent of the automation object.
     *
     *  @param part id part of the automation object.
     *
     *  @return IAutomationObject which matches with the <code>part</code>. 
     *  If no object 
     *  is found or multiple objects are found, throw an exception.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function resolveIDPartToSingleObject(parent:IAutomationObject,
                                         part:AutomationIDPart):IAutomationObject;
    
    /**
     *  Resolves an id part to an Array of automation objects.
     * 
     *  @param parent Parent of the automation object.
     *
     *  @param part id part of the automation object.
     *
     *  @return Array of automation objects which match <code>part</code>.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function resolveIDPart(parent:IAutomationObject,
                           part:AutomationIDPart):Array;

    /**
     *  Returns an id for the given object that can be used 
     *  with the <code>resolveID()</code> method.
     *
     *  @param obj Automation object.
     *
     *  @param relativeToParent Parent of the automation object.
     *  
     *  @return AutomationID object which represents the Automation object.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function createID(obj:IAutomationObject, 
                      relativeToParent:IAutomationObject = null):AutomationID;

    /**
     *  Returns an id part for the given object that can be used in the <code>resolveIDPart()</code> method.
     * 
     *  @param obj The automation object.
     *
     *  @param parent Parent of the automation object.
     *  
     *  @return AutomationIDPart object which represents the Automation object.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function createIDPart(obj:IAutomationObject, 
                          parent:IAutomationObject = null):AutomationIDPart;

    /**
     *  Indicates whether an automation object should be visible within
     *  the hierarchy.
     *
     *  @param obj The automation object.
     * 
     *  @return <code>true</code> if the object should be shown within the
     *  automation hierarchy.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function showInHierarchy(obj:IAutomationObject):Boolean;

    /**
     *  @private
     */
    function set automationEnvironment(env:Object):void;

    /**
     *  The automation environment for this automation manager.
     *  The automation environment provides information about the
     *  objects and properties of testable components needed for communicating
     *  with agent tools.
     *
     *  <p>The value of this property must implement the IAutomationEnvironment interface.</p>
     *
     *  @see mx.automation.IAutomationEnvironment
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function get automationEnvironment():Object;

    /**
     *  Increments the cache counter. The automation mechanism  
     *  caches both an object's properties and its children. The cache
     *  exists for both performance reasons, and so that an objects state
     *  prior to a recording can be captured. Each call to the 
     *  <code>incrementCacheCounter()</code> method
     *  increments a counter and each call to the 
     *  <code>decrementCacheCounter()</code> method 
     *  decrements the cache counter. When the counter reaches zero the
     *  cache is cleared. 
     *
     *  <p>It's important that testing tools only use the
     *  cache when they are certain that the state of the Flex application
     *  is frozen and the user cannot interact with it. For example,
     *  when an automation event is recorded, a testing tool might need to make
     *  several calls to  the <code>getChildren()</code> method or the
     * <code>getProperties()</code> method to create a testing
     *  script line. To do this, it would wrap all the calls up in 
     *  start/stop cache calls.</p>
     *
     *  <p>Internally, the AutomationManager forcibly clears the cache
     *  before an end-user interaction that might trigger an automation
     *  event. It then increments the cache counter and decrements the
     *  counter after the automation event is dispatched. Testing tools can
     *  prevent the count from reaching zero by calling the <code>incrementCacheCounter()</code> 
     *  method in their record handler.</p>
     *
     *  @return the current cache counter.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function incrementCacheCounter():int;

    /**
     *  Decrement the cache counter. The cache is cleared when
     *  the count reaches zero.
     *
     *  @param clearNow If <code>true</code>, clear the cache regardless of the cache counter.
     * 
     *  @return Current cache counter.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function decrementCacheCounter(clearNow:Boolean = false):int;


    /**
     * Tests if the provided target needs to wait until a previous
     * operation completes.
     * 
     * @param target Target to check for synchronization or
     * <code>null</code> to synchronize on any running operations.
     * 
     * @return <code>true</code> if synchronization is complete, <code>false</code> otherwise.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function isSynchronized(target:IAutomationObject):Boolean;

    /**
     *  Records the event.
     *
     *  @param recorder The automation object on which the event is to be recorded.
     *
     *  @param event The actual event which needs to be recorded. 
     *
     *  @param cacheable Controls the caching of the event that is recorded. 
     *  During a mouse-down, mouse-up sequence, the automation mechanism tries to record the most 
     *  important or suitable event rather than all the events. 
     *
     *  For example, if you have a List control which has a button in its item renderer. 
     *  When the user clicks on the button, the automation mechanism only records 
     *  the <code>click</code> event for the button, but ignores the <code>select</code> event 
     *  generated from the List control.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function recordAutomatableEvent(recorder:IAutomationObject, event:Event,
                                    cacheable:Boolean = false):void;
    
    /**
     *  Replays the specified event. A component author should call 
     *  the <code>super.replayAutomatableEvent()</code> method 
     *  in case default replay behavior has been defined in a superclass.
     *
     *  @param event Event to replay.
     *
     *  @return <code>true</code> if the replay was successful. 
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function replayAutomatableEvent(event:AutomationReplayEvent):Boolean;
    
    
     /**
     *  Records the  custom event.
     *
     *  @param recordEvent -  The AutomationRecordEvent that specifies that it is a custom evnet; the type is customRecord.
     *
     *  For example, if you want to record a custom event without writing a delegate and providing the details
     *  in an environment file, you can use this interface to record the custom event. You should listen to
     *  the AutomationPlaybackEvent, handle the replay, and prevent the default on the AutomationPlaybackEvent.
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    function recordCustomAutomationEvent(customEvent:AutomationRecordEvent):Boolean;

}

}