////////////////////////////////////////////////////////////////////////////////
//
// 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 false
.
*
* @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 false
.
*
* @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 false
.
*
* @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 true
, only include verification properties.
*
* @param forDescription If true
, 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 true
if an object and all of its parents are visible.
*
* @param obj DisplayObject.
*
* @return true
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 rid
.
* 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 rid
.
*
* @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 part
.
* 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 part
.
*
* @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 resolveID()
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 resolveIDPart()
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 true
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.
*
*
The value of this property must implement the IAutomationEnvironment interface.
* * @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 *incrementCacheCounter()
method
* increments a counter and each call to the
* decrementCacheCounter()
method
* decrements the cache counter. When the counter reaches zero the
* cache is cleared.
*
* 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 getChildren()
method or the
* getProperties()
method to create a testing
* script line. To do this, it would wrap all the calls up in
* start/stop cache calls.
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 incrementCacheCounter()
* method in their record handler.
true
, 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
* null
to synchronize on any running operations.
*
* @return true
if synchronization is complete, false
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 click
event for the button, but ignores the select
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 super.replayAutomatableEvent()
method
* in case default replay behavior has been defined in a superclass.
*
* @param event Event to replay.
*
* @return true
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;
}
}