1 /*
   2  * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.javafx.robot;
  27 
  28 import javafx.scene.input.KeyCode;
  29 import javafx.scene.input.MouseButton;
  30 
  31 /**
  32  * Defines interface for generation of FX level events for purposes of test
  33  * automation, self running demos and other applications where control of the
  34  * mouse and keyboard is needed.
  35  * 
  36  */
  37 public abstract class FXRobot {
  38     protected boolean autoWait = false;
  39 
  40     /**
  41      * Block until events in the queue are processed.
  42      */
  43     public abstract void waitForIdle();
  44     
  45     /**
  46      * Whether to wait for events to be processed after each robot command
  47      * @param wait if true, wait until events in the queue are processed
  48      */
  49     public void setAutoWaitForIdle(boolean wait) {
  50         autoWait = wait;
  51     }
  52 
  53     /**
  54      * Generate a key pressed event.
  55      * @param code key code for this event
  56      */
  57     public abstract void keyPress(KeyCode code);
  58 
  59     /**
  60      * Generate a key released event.
  61      *
  62      * Note that KeyTyped event will not be generated automatically on key
  63      * released,
  64      * {@link #keyType(javafx.scene.input.KeyCode, java.lang.String)} will
  65      * need to be called explicitly.
  66      * 
  67      * @param code key code for this event
  68      */
  69     public abstract void keyRelease(KeyCode code);
  70 
  71     /**
  72      * Generate a key typed event. The {@code keyChar} argument will need to
  73      * depend on what character is generated by this event. That is, the user
  74      * will need to take into account different modifiers currently applied and
  75      * so forth. If shift is presumed to be pressed, the char will be "A",
  76      * otherwise it will be "a".
  77      *
  78      * @param code key code for this event
  79      * @param keyChar char for this event 
  80      */
  81     public abstract void keyType(KeyCode code, String keyChar);
  82 
  83     /**
  84      * Generate a mouse moved event.
  85      * 
  86      * @param x scene coordinate x
  87      * @param y scene coordinate y
  88      */
  89     public abstract void mouseMove(int x, int y);
  90 
  91     /**
  92      * Generate a mouse press event with specified click count.
  93      *
  94      * Note that a multi-click gesture consists of multiple sets of 
  95      * MousePressed/MouseReleased/MouseClicked events, with second and following
  96      * sets having appropriate click count set.
  97      * <br>
  98      * For example, a double click is emulated with:
  99      * {@code press/release/click} followed by {@code press(2)/release(2)/click(2)}
 100      *
 101      * @param button button to have generated the event
 102      * @param clickCount number of clicks for this event
 103      */
 104     public abstract void mousePress(MouseButton button, int clickCount);
 105 
 106     /**
 107      * Generate a mouse release event with specified click count.
 108      *
 109      * Note that this method will not generate a MouseClicked event, use
 110      * {@link #mouseClick(javafx.scene.input.MouseButton) } for that.
 111      *
 112      * Note that a multi-click gesture consists of multiple sets of
 113      * MousePressed/MouseReleased/MouseClicked events, with second and following
 114      * sets having appropriate click count set.
 115      * <br>
 116      * For example, a double click is emulated with:
 117      * {@code press/release/click} followed by {@code press(2)/release(2)/click(2)}
 118      *
 119      * @param button button to have generated the event
 120      * @param clickCount number of clicks for this event
 121      */
 122     public abstract void mouseRelease(MouseButton button, int clickCount);
 123     
 124     /**
 125      * Generate a mouse clicked event with specified click count.
 126      *
 127      * Note that a multi-click gesture consists of multiple sets of
 128      * MousePressed/MouseReleased/MouseClicked events, with second and following
 129      * sets having appropriate click count set.
 130      * <br>
 131      * For example, a double click is emulated with:
 132      * {@code press/release/click} followed by {@code press(2)/release(2)/click(2)}
 133      *
 134      * @param button button to have generated the event
 135      * @param clickCount number of clicks for this event
 136      */
 137     public abstract void mouseClick(MouseButton button, int clickCount);
 138 
 139     /**
 140      * Generate a mouse pressed event with click count of 1.
 141      *
 142      * @param button button to have generated the event
 143      */
 144     public void mousePress(MouseButton button) {
 145         mousePress(button, 1);
 146     }
 147     
 148     /**
 149      * Generate a mouse pressed event with click count of 1.
 150      *
 151      * Note that this method will not generate a MouseClicked event, use
 152      * {@link #mouseClick(javafx.scene.input.MouseButton) } for that.
 153      *
 154      * @param button button to have generated the event
 155      */
 156     public void mouseRelease(MouseButton button) {
 157         mouseRelease(button, 1);
 158     }
 159 
 160     /**
 161      * Generate a mouse clicked event with click count of 1.
 162      *
 163      * @param button button to have generated the event
 164      */
 165     public void mouseClick(MouseButton button) {
 166         mouseClick(button, 1);
 167     }
 168 
 169     /**
 170      * Generate a mouse dragged event.
 171      *
 172      * @param button button to have generated the event
 173      */
 174     public abstract void mouseDrag(MouseButton button);
 175 
 176     /**
 177      * Generate a mouse wheel event.
 178      *
 179      * @param wheelAmt amount the wheel has turned of wheel turning
 180      */
 181     public abstract void mouseWheel(int wheelAmt);
 182 
 183     /**
 184      * Returns pixel color at specified scene coordinates in IntARGB format,
 185      * {@code 0} if the passed coordinates are outside of the scene's bounds or
 186      * if pixel grabbing isn't supported.
 187      * 
 188      * @param x scene coordinate
 189      * @param y scene coordinate
 190      * @return pixel color in IntARGB format or {@code 0} if outside of scene
 191      * bounds or if pixel grabbing isn't supported
 192      */
 193     public abstract int getPixelColor(int x, int y);
 194 
 195     /**
 196      * Returns a {@link FXRobotImage} object representing in image with contents 
 197      * of the scene at specified coordinates, or null if scene pixel capturing
 198      * isn't supported.
 199      *
 200      * Implementation note: current implementation ignores passed parameters and
 201      * always captures complete scene.
 202      * 
 203      * @param x scene coordinate
 204      * @param y scene coordinate
 205      * @param width of the area to capture
 206      * @param height of the area to capture
 207      * @return {@code FXRobotImage} containing captured pixels or null if pixel
 208      * capturing isn't supproted
 209      */
 210     public abstract FXRobotImage getSceneCapture(int x, int y, int width, int height);
 211 }