001    /*
002     * Created on Sep 21, 2007
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 @2007-2010 the original author or authors.
015     */
016    package org.fest.swing.core;
017    
018    import static org.fest.swing.util.Arrays.copyOf;
019    
020    import java.awt.Event;
021    import java.awt.event.KeyEvent;
022    
023    import org.fest.swing.util.Platform;
024    
025    /**
026     * Understands information about pressing a keyboard key.
027     * <p>
028     * Examples:
029     * </p>
030     * <p>
031     * Specify that 'CTRL' + 'C' should be pressed:
032     * <pre>
033     * // import static org.fest.swing.fixture.KeyPressInfo.*;
034     * KeyPressInfo i = key(VK_C).modifiers(CTRL_MASK);
035     * </pre>
036     * </p>
037     * <p>
038     * Specify that 'SHIFT' + 'R' should be pressed:
039     * <pre>
040     * // import static org.fest.swing.fixture.KeyPressInfo.*;
041     * KeyPressInfo i = key(VK_R).modifiers(SHIFT_MASK);
042     * </pre>
043     * </p>
044     * <p>
045     * For platform-safe mask pressing (e.g. 'Control' in Windows or 'Command' in MacOS) use
046     * <code>{@link Platform#controlOrCommandMask()}</code>.
047     * </p>
048     *
049     * @author Alex Ruiz
050     * @author Yvonne Wang
051     */
052    public final class KeyPressInfo {
053    
054      private final int keyCode;
055      private int[] modifiers;
056    
057      /**
058       * Specifies the code of the key to press, without any modifiers (e.g.
059       * <code>{@link KeyEvent#VK_C KeyEvent.VK_C}</code>.)
060       * @param keyCode the code of the key to press.
061       * @return the created <code>KeyPressInfo</code>.
062       */
063      public static KeyPressInfo keyCode(int keyCode) {
064        return new KeyPressInfo(keyCode, new int[0]);
065      }
066    
067      private KeyPressInfo(int keyCode, int[] modifiers) {
068        this.keyCode = keyCode;
069        this.modifiers = modifiers;
070      }
071    
072      /**
073       * Returns the code of the key to press.
074       * @return the code of the key to press.
075       */
076      public int keyCode() { return keyCode; }
077    
078      /**
079       * Returns the modifiers to use when pressing <code>{@link #keyCode() the specified key}</code>.
080       * @return the modifiers to use.
081       */
082      public int[] modifiers() {
083        return copyOf(modifiers);
084      }
085    
086      /**
087       * Specifies the modifiers to use when pressing <code>{@link #keyCode() the specified key}</code> (e.g.
088       * <code>{@link Event#CTRL_MASK Event.CTRL_MASK}</code>.)
089       * <p>
090       * For platform-safe mask pressing (e.g. 'Control' in Windows or 'Command' in MacOS) use
091       * <code>{@link Platform#controlOrCommandMask()}</code>.
092       * </p>
093       * @param newModifiers the new modifiers to use.
094       * @return this object.
095       * @throws NullPointerException if <code>newModifiers</code> is <code>null</code>.
096       */
097      public KeyPressInfo modifiers(int... newModifiers) {
098        if (newModifiers == null) throw new NullPointerException("The array of modifiers should not be null");
099        modifiers = copyOf(newModifiers);
100        return this;
101      }
102    }