automationhandler.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)AutomationHandler.java	1.7 02/07/24 @(#)
 *
 * Copyright (c) 2001-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package com.sun.midp.lcdui;

/**
 * The automation handler class. This is an abstract class which
 * which provides options to record and playback a sequence of events
 * for automation purposes, as well as capture the contents of the
 * screen.
 */
public interface AutomationHandler {
    /**
     * The identifier for the 'start recording' action to be used
     * when registering a new hotkey. The default hotkey for this
     * action is 'F1'.
     */
    public static final int START_RECORDING = 0;

    /**
     * The identifier for the 'stop recording' action to be used
     * when registering a new hotkey. The default hotkey for this
     * action is 'F2'.
     */
    public static final int STOP_RECORDING  = 1;

    /**
     * The identifier for the 'capture screen' action to be used
     * when registering a new hotkey. The default hotkey for this
     * action is 'F3'.
     */
    public static final int CAPTURE_SCREEN  = 2;

    /**
     * Start recording an event sequence. Any event sequence currently
     * being recorded will be destroyed and a new event sequence will
     * be started.
     */
    public void startEventSequence();

    /**
     * Stop recording an event sequence. This will stop recording the
     * current event sequence and capture the current contents of the
     * screen. It will then return an EventSequence object which is
     * the representation of the entire event sequence as well as the
     * screen capture resulting at the end of the sequence. If no events
     * occurred during the capture, the sequence will simply be a timed
     * delay with a screen capture. The timed delay will be the time delay
     * between the call to startEventSequence() and stopEventSequence().
     *
     * If stopEventSequence() is called without previously calling
     * startEventSequence(), an EventSequence will be returned which is
     * essentially "empty" and only contains the current contents of
     * the captured screen.
     *
     * @return EventSequence The sequence of events recorded as well as
     *                       the screen capture recorded at the end of
     *                       the sequence of events.
     */
    public EventSequence stopEventSequence();

    /**
     * Establish a SequenceHandler to handle the completion of EventSequences.
     * and screen captures which occur as a result of a 'hotkey' press.
     * If a sequence handler is set, that handler will be called when any
     * event sequence is completed, either as a result of stopEventSequence()
     * being called, or as a result of some "hot key" being pressed which
     * the event handler recognizes as a signal to stop event recording.
     * The EventSequence object passed to the handler will be the same as
     * the return result of the stopEventSequence() method. If a handler has
     * already been set, and this method is called again the old handler will
     * be discarded and the new handler will be used. If 'null' is passed,
     * any previous handler will be discarded.
     *
     * @param handler The SequenceHandler which will get the callback
     *                whenever an event sequence is completed.
     * @throws IllegalArgumentException If this particular port or platform
     *                                  cannot support hotkey activation, this
     *                                  method will throw an exception
     */
    public void registerSequenceHandler(SequenceHandler handler)
        throws IllegalArgumentException;

    /**
     * Establish a specific key code for the given action to serve as
     * a 'hotkey'. The action must be one of START_RECORDING, STOP_RECORDING,
     * or CAPTURE_SCREEN.
     *
     * @param action The action to register the hotkey for, one of
     *               START_RECORDING, STOP_RECORDING, or CAPTURE_SCREEN.
     * @param keyCode The key code of the new hotkey
     * @throws IllegalArgumentException If this particular port or platform
     *                                  cannot support hotkey activation, this
     *                                  method will throw an exception. An
     *                                  exception will also be thrown
     *                                  if the requested action or key code is
     *                                  invalid.
     */
    public void registerHotKey(int action, int keyCode)
        throws IllegalArgumentException;

    /**
     * Replay a given event sequence. This will replay a sequence of
     * events represented in the given EventSequence object. It will
     * then capture the contents of the screen at the end of the event
     * sequence and compare it to the screen capture that is included
     * in the EventSequence object.
     *
     * @param sequence The EventSequence object to replay and test
     * @return True if the screen capture at the end of replaying
     *         the given event sequence matches that which is stored
     *         in the given EventSequence object.
     */
    public boolean replayEventSequence(EventSequence sequence);

    /**
     * Replay a given event sequence. This will replay a sequence of
     * events represented in the given EventSequence object. It will
     * then capture the contents of the screen at the end of the event
     * sequence and compare it to the screen capture that is included
     * in the EventSequence object.
     *
     * @param sequence The EventSequence object to replay and test
     * @param speed The factor by which to modify the replay speed of
     *              the event sequence. This is on a scale of 100,
     *              meaning a value of 100 would be normal speed,
     *              50 would be half speed, and 200 would be double
     *              speed.
     *
     * @return True if the screen capture at the end of replaying
     *         the given event sequence matches that which is stored
     *         in the given EventSequence object.
     */
    public boolean replayEventSequence(EventSequence sequence,
                                                int speed);

    /**
     * Update the screen capture for this event sequence. Over time, the
     * screen captures in a stored event sequence may become out of date.
     * Calling this method will run the given event sequence, capture
     * the resulting screen, and return the same EventSequence object
     * with the updated screen value.
     *
     * @param sequence The EventSequence to run and update the screen for
     * @return The updated EventSequence with the new captured screen value
     */
    public EventSequence updateScreenForSequence(
        EventSequence sequence);

    /**
     * Capture the current contents of the physical display in the form of a
     * byte array. The byte array may be some reduced form of the display, such
     * as a checksum or hash, but must be guaranteed unique for the display
     * such that no two differing displays will have the same return value
     *
     * @return The byte[] of the captured screen contents
     */
    public byte[] captureScreen();

}