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    
008    package edu.wpi.first.wpilibj.buttons;
009    
010    import 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     */
025    public 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 
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 
066         */
067        public void cancelWhenPressed(final Command command) {
068            cancelWhenActive(command);
069        }
070    }