/*
** Module   : SendSpecialKey.java
** Abstract : implement the send-special-key step in a test
**
** Copyright (c) 2009, Golden Code Development Corporation.
**
** -#- -I- --Date-- -----------------------Description------------------------
** 001 GES 20090113 Implement the send-special-key step in a test.
*/

/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU Affero General Public License for more details.
**
** You should have received a copy of the GNU Affero General Public License
** along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

package com.goldencode.harness.test;

import com.goldencode.harness.*;
import com.goldencode.harness.terminal.*;

/**
 * Implement the send-special-key step in a test. This directive has the
 * effect of sending a single special key to the back end (terminal). The
 * key is specified as a symbolic key name.
 * <p>
 * The following symbolic key names are valid:
 * <p>
 * <pre>
 * VK_ESCAPE
 * VK_F1
 * VK_F2
 * VK_F3
 * VK_F4
 * VK_F5
 * VK_F6
 * VK_F7
 * VK_F8
 * VK_F9
 * VK_F10
 * VK_F11
 * VK_F12
 * VK_UP
 * VK_DOWN
 * VK_LEFT
 * VK_RIGHT
 * VK_PAGE_DOWN
 * VK_PAGE_UP
 * VK_INSERT
 * VK_DELETE
 * VK_BACK_SPACE
 * VK_HOME
 * VK_END
 * VK_NUM_LOCK
 * VK_CAPS_LOCK
 * VK_PAUSE
 * VK_TAB
 * VK_ENTER
 * </pre>
 * <p>
 * As with all key processing, it is possible to specify modifier keys that
 * are sent along with each key. Modifier keys include the control, alt and
 * shift keys. This allows a key that is sent to be interpreted differently.
 * For example, the F1 key will be interpreted as CTRL-F1 is the control
 * modifier is included. Zero or more modifiers can be sent with each key.
 * <p>
 * Modifiers cannot be sent as a separate key (by themselves).
 * <p>
 * The following symbolic modifier names are valid:
 * <p>
 * <pre>
 * CTRL
 * ALT
 * SHIFT
 * </pre>
 */
public class SendSpecialKey
extends SendKey
{
   /** Short name for the activity. */
   private static final String NAME = "SEND-SPECIAL-KEY";
   
   /**
    * Construct an instance of a step which sends keys to the terminal.
    *
    * @param    value
    *           The symbolic name of the special key to send. If
    *           <code>null</code> or the empty string then this directive is
    *           a no-operation.
    * @param    modifiers
    *           Zero or more modifier key names (CTRL, ALT and/or SHIFT).
    *           These can be separated by spaces, commas, plus signs or any
    *           other separator (e.g. "CTRL,ALT"). Case will be ignored. This
    *           may be empty or <code>null</code> which is the equivalent of
    *           no modifiers. If not <code>null</code>, this specifies
    *           modifier keys that are to be treated as "pressed" when the
    *           key(s) are sent.
    */
   public SendSpecialKey(String value, String modifiers)
   {
      super(NAME, value, modifiers);
   }
   
   /**
    * Send a single special key to the back end (terminal).
    * <p>
    * The following key names are valid:
    * <p>
    * <pre>
    * VK_ESCAPE
    * VK_F1
    * VK_F2
    * VK_F3
    * VK_F4
    * VK_F5
    * VK_F6
    * VK_F7
    * VK_F8
    * VK_F9
    * VK_F10
    * VK_F11
    * VK_F12
    * VK_UP
    * VK_DOWN
    * VK_LEFT
    * VK_RIGHT
    * VK_PAGE_DOWN
    * VK_PAGE_UP
    * VK_INSERT
    * VK_DELETE
    * VK_BACK_SPACE
    * VK_HOME
    * VK_END
    * VK_NUM_LOCK
    * VK_CAPS_LOCK
    * VK_PAUSE
    * VK_TAB
    * VK_ENTER
    * </pre>
    *
    * @param    term
    *           The terminal that represents the system under test.
    * @param    value
    *           A symbolic special key name. Case will be ignored. If empty
    *           or <code>null</code>, this is a no-operation.
    * @param    modifiers
    *           Zero or more modifier key names (CTRL, ALT and/or SHIFT).
    *           These can be separated by spaces, commas, plus signs or any
    *           other separator (e.g. "CTRL,ALT"). Case will be ignored. This
    *           may be empty or <code>null</code> which is the equivalent of
    *           no modifiers. If not <code>null</code>, this specifies
    *           modifier keys that are to be treated as "pressed" when the
    *           key(s) are sent.
    */
   protected void send(Terminal term, String value, String modifiers)
   {
      if (value != null && value.length() > 0)
      {
         term.sendSpecialKey(value, modifiers);
      }
      
      setStatus(Status.PASSED, null);
   }
}
