001    /*
002     * Created on Jul 8, 2008
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2008-2010 the original author or authors.
015     */
016    package org.fest.swing.fixture;
017    
018    import java.awt.event.KeyEvent;
019    
020    import org.fest.swing.core.KeyPressInfo;
021    import org.fest.swing.util.Platform;
022    
023    /**
024     * Understands simulation of keyboard input on a GUI component.
025     *
026     * @author Alex Ruiz
027     */
028    public interface KeyboardInputSimulationFixture {
029    
030      /**
031       * Simulates a user pressing and releasing the given keys on this fixture's GUI component.
032       * @param keyCodes one or more codes of the keys to press.
033       * @return this fixture.
034       * @throws NullPointerException if the given array of codes is <code>null</code>.
035       * @throws IllegalArgumentException if any of the given code is not a valid key code.
036       * @throws IllegalStateException if the component is disabled.
037       * @throws IllegalStateException if the component is not showing on the screen.
038       * @see java.awt.event.KeyEvent
039       */
040      KeyboardInputSimulationFixture pressAndReleaseKeys(int...keyCodes);
041    
042      /**
043       * Simulates a user pressing given key on this fixture's GUI component.
044       * @param keyCode the code of the key to press.
045       * @return this fixture.
046       * @throws IllegalArgumentException if the given code is not a valid key code.
047       * @throws IllegalStateException if the component is disabled.
048       * @throws IllegalStateException if the component is not showing on the screen.
049       * @see java.awt.event.KeyEvent
050       */
051      KeyboardInputSimulationFixture pressKey(int keyCode);
052    
053      /**
054       * Simulates a user pressing given key with the given modifiers on this fixture's GUI component.
055       * Modifiers is a mask from the available <code>{@link java.awt.event.InputEvent}</code> masks.
056       * <p>
057       * The following code listing shows how to press 'CTRL' + 'C' in a platform-safe way:
058       * <pre>
059       * JTextComponentFixture textBox = dialog.textBox(&quot;username&quot;);
060       * textBox.selectAll()
061       *        .pressAndReleaseKey(key(<code>{@link KeyEvent#VK_C VK_C}</code>).modifiers({@link Platform#controlOrCommandMask() controlOrCommandMask}()));
062       * </pre>
063       * </p>
064       * @param keyPressInfo specifies the key and modifiers to press.
065       * @return this fixture.
066       * @throws NullPointerException if the given <code>KeyPressInfo</code> is <code>null</code>.
067       * @throws IllegalArgumentException if the given code is not a valid key code.
068       * @throws IllegalStateException if the component is disabled.
069       * @throws IllegalStateException if the component is not showing on the screen.
070       */
071      KeyboardInputSimulationFixture pressAndReleaseKey(KeyPressInfo keyPressInfo);
072    
073      /**
074       * Simulates a user releasing the given key on this fixture's GUI component.
075       * @param keyCode the code of the key to release.
076       * @return this fixture.
077       * @throws IllegalArgumentException if the given code is not a valid key code.
078       * @throws IllegalStateException if the component is disabled.
079       * @throws IllegalStateException if the component is not showing on the screen.
080       * @see java.awt.event.KeyEvent
081       */
082      KeyboardInputSimulationFixture releaseKey(int keyCode);
083    }