001/*----------------------------------------------------------------------------*/
002/* Copyright (c) FIRST 2008-2017. All Rights Reserved.                        */
003/* Open Source Software - may be modified and shared by FRC teams. The code   */
004/* must be accompanied by the FIRST BSD license file in the root directory of */
005/* the project.                                                               */
006/*----------------------------------------------------------------------------*/
007
008package edu.wpi.first.wpilibj.buttons;
009
010import edu.wpi.first.wpilibj.command.Command;
011
012/**
013 * This class provides an easy way to link commands to OI inputs.
014 *
015 * <p>It is very easy to link a button to a command. For instance, you could link the trigger button
016 * of a joystick to a "score" command.
017 *
018 * <p>This class represents a subclass of Trigger that is specifically aimed at buttons on an
019 * operator interface as a common use case of the more generalized Trigger objects. This is a simple
020 * wrapper around Trigger with the method names renamed to fit the Button object use.
021 */
022public abstract class Button extends Trigger {
023
024  /**
025   * Starts the given command whenever the button is newly pressed.
026   *
027   * @param command the command to start
028   */
029  public void whenPressed(final Command command) {
030    whenActive(command);
031  }
032
033  /**
034   * Constantly starts the given command while the button is held.
035   *
036   * {@link Command#start()} will be called repeatedly while the button is held, and will be
037   * canceled when the button is released.
038   *
039   * @param command the command to start
040   */
041  public void whileHeld(final Command command) {
042    whileActive(command);
043  }
044
045  /**
046   * Starts the command when the button is released.
047   *
048   * @param command the command to start
049   */
050  public void whenReleased(final Command command) {
051    whenInactive(command);
052  }
053
054  /**
055   * Toggles the command whenever the button is pressed (on then off then on).
056   *
057   * @param command the command to start
058   */
059  public void toggleWhenPressed(final Command command) {
060    toggleWhenActive(command);
061  }
062
063  /**
064   * Cancel the command when the button is pressed.
065   *
066   * @param command the command to start
067   */
068  public void cancelWhenPressed(final Command command) {
069    cancelWhenActive(command);
070  }
071}