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