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.wpilibj2.command.button;
006
007import edu.wpi.first.wpilibj2.command.Command;
008import edu.wpi.first.wpilibj2.command.Subsystem;
009import java.util.function.BooleanSupplier;
010
011/**
012 * This class provides an easy way to link commands to OI inputs.
013 *
014 * <p>It is very easy to link a button to a command. For instance, you could link the trigger button
015 * of a joystick to a "score" command.
016 *
017 * <p>This class represents a subclass of Trigger that is specifically aimed at buttons on an
018 * operator interface as a common use case of the more generalized Trigger objects. This is a simple
019 * wrapper around Trigger with the method names renamed to fit the Button object use.
020 */
021public class Button extends Trigger {
022  /**
023   * Default constructor; creates a button that is never pressed (unless {@link Button#get()} is
024   * overridden).
025   */
026  public Button() {}
027
028  /**
029   * Creates a new button with the given condition determining whether it is pressed.
030   *
031   * @param isPressed returns whether or not the trigger should be active
032   */
033  public Button(BooleanSupplier isPressed) {
034    super(isPressed);
035  }
036
037  /**
038   * Starts the given command whenever the button is newly pressed.
039   *
040   * @param command the command to start
041   * @param interruptible whether the command is interruptible
042   * @return this button, so calls can be chained
043   */
044  public Button whenPressed(final Command command, boolean interruptible) {
045    whenActive(command, interruptible);
046    return this;
047  }
048
049  /**
050   * Starts the given command whenever the button is newly pressed. The command is set to be
051   * interruptible.
052   *
053   * @param command the command to start
054   * @return this button, so calls can be chained
055   */
056  public Button whenPressed(final Command command) {
057    whenActive(command);
058    return this;
059  }
060
061  /**
062   * Runs the given runnable whenever the button is newly pressed.
063   *
064   * @param toRun the runnable to run
065   * @param requirements the required subsystems
066   * @return this button, so calls can be chained
067   */
068  public Button whenPressed(final Runnable toRun, Subsystem... requirements) {
069    whenActive(toRun, requirements);
070    return this;
071  }
072
073  /**
074   * Constantly starts the given command while the button is held.
075   *
076   * <p>{@link Command#schedule(boolean)} will be called repeatedly while the button is held, and
077   * will be canceled when the button is released.
078   *
079   * @param command the command to start
080   * @param interruptible whether the command is interruptible
081   * @return this button, so calls can be chained
082   */
083  public Button whileHeld(final Command command, boolean interruptible) {
084    whileActiveContinuous(command, interruptible);
085    return this;
086  }
087
088  /**
089   * Constantly starts the given command while the button is held.
090   *
091   * <p>{@link Command#schedule(boolean)} will be called repeatedly while the button is held, and
092   * will be canceled when the button is released. The command is set to be interruptible.
093   *
094   * @param command the command to start
095   * @return this button, so calls can be chained
096   */
097  public Button whileHeld(final Command command) {
098    whileActiveContinuous(command);
099    return this;
100  }
101
102  /**
103   * Constantly runs the given runnable while the button is held.
104   *
105   * @param toRun the runnable to run
106   * @param requirements the required subsystems
107   * @return this button, so calls can be chained
108   */
109  public Button whileHeld(final Runnable toRun, Subsystem... requirements) {
110    whileActiveContinuous(toRun, requirements);
111    return this;
112  }
113
114  /**
115   * Starts the given command when the button is first pressed, and cancels it when it is released,
116   * but does not start it again if it ends or is otherwise interrupted.
117   *
118   * @param command the command to start
119   * @param interruptible whether the command is interruptible
120   * @return this button, so calls can be chained
121   */
122  public Button whenHeld(final Command command, boolean interruptible) {
123    whileActiveOnce(command, interruptible);
124    return this;
125  }
126
127  /**
128   * Starts the given command when the button is first pressed, and cancels it when it is released,
129   * but does not start it again if it ends or is otherwise interrupted. The command is set to be
130   * interruptible.
131   *
132   * @param command the command to start
133   * @return this button, so calls can be chained
134   */
135  public Button whenHeld(final Command command) {
136    whileActiveOnce(command, true);
137    return this;
138  }
139
140  /**
141   * Starts the command when the button is released.
142   *
143   * @param command the command to start
144   * @param interruptible whether the command is interruptible
145   * @return this button, so calls can be chained
146   */
147  public Button whenReleased(final Command command, boolean interruptible) {
148    whenInactive(command, interruptible);
149    return this;
150  }
151
152  /**
153   * Starts the command when the button is released. The command is set to be interruptible.
154   *
155   * @param command the command to start
156   * @return this button, so calls can be chained
157   */
158  public Button whenReleased(final Command command) {
159    whenInactive(command);
160    return this;
161  }
162
163  /**
164   * Runs the given runnable when the button is released.
165   *
166   * @param toRun the runnable to run
167   * @param requirements the required subsystems
168   * @return this button, so calls can be chained
169   */
170  public Button whenReleased(final Runnable toRun, Subsystem... requirements) {
171    whenInactive(toRun, requirements);
172    return this;
173  }
174
175  /**
176   * Toggles the command whenever the button is pressed (on then off then on).
177   *
178   * @param command the command to start
179   * @param interruptible whether the command is interruptible
180   * @return this button, so calls can be chained
181   */
182  public Button toggleWhenPressed(final Command command, boolean interruptible) {
183    toggleWhenActive(command, interruptible);
184    return this;
185  }
186
187  /**
188   * Toggles the command whenever the button is pressed (on then off then on). The command is set to
189   * be interruptible.
190   *
191   * @param command the command to start
192   * @return this button, so calls can be chained
193   */
194  public Button toggleWhenPressed(final Command command) {
195    toggleWhenActive(command);
196    return this;
197  }
198
199  /**
200   * Cancels the command when the button is pressed.
201   *
202   * @param command the command to start
203   * @return this button, so calls can be chained
204   */
205  public Button cancelWhenPressed(final Command command) {
206    cancelWhenActive(command);
207    return this;
208  }
209}