001/*----------------------------------------------------------------------------*/
002/* Copyright (c) FIRST 2008-2012. 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 * It is very easy to link a button to a command.  For instance, you could
016 * link the trigger button of a joystick to a "score" command.
017 *
018 * This class represents a subclass of Trigger that is specifically aimed at
019 * buttons on an operator interface as a common use case of the more generalized
020 * Trigger objects. This is a simple wrapper around Trigger with the method names
021 * renamed to fit the Button object use.
022 *
023 * @author brad
024 */
025public abstract class Button extends Trigger {
026
027    /**
028     * Starts the given command whenever the button is newly pressed.
029     * @param command the command to start
030     */
031    public void whenPressed(final Command command) {
032        whenActive(command);
033    }
034
035    /**
036     * Constantly starts the given command while the button is held.
037     *
038     * {@link Command#start()} will be called repeatedly while the button is held,
039     * and will be canceled when the button is released.
040     *
041     * @param command the command to start
042     */
043    public void whileHeld(final Command command) {
044        whileActive(command);
045    }
046
047    /**
048     * Starts the command when the button is released
049     * @param command the command to start
050     */
051    public void whenReleased(final Command command) {
052        whenInactive(command);
053    }
054
055    /**
056     * Toggles the command whenever the button is pressed (on then off then on)
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     * @param command the command to start
066     */
067    public void cancelWhenPressed(final Command command) {
068        cancelWhenActive(command);
069    }
070}