Class Trigger

java.lang.Object
org.wpilib.command3.Trigger
All Implemented Interfaces:
BooleanSupplier
Direct Known Subclasses:
InternalButton, JoystickButton, NetworkButton, POVButton
public class Trigger extends Object implements BooleanSupplier
Triggers allow users to specify conditions for when commands should run. Triggers can be set up to read from joystick and controller buttons (eg CommandGamepad.faceDown()) or be customized to read sensor values or any other arbitrary true/false condition.

It is very easy to link a button to a command. For instance, you could link the trigger button of a joystick to a "score" command.

Triggers can easily be composed for advanced functionality using the and(BooleanSupplier), or(BooleanSupplier), negate() operators.

Trigger bindings created inside a running command will only be active while that command is running. This is useful for defining trigger-based behavior only in a certain scope and avoids needing to create dozens of global triggers. Any commands scheduled by these triggers will be canceled when the enclosing command exits. 

Command shootWhileAiming = Command.noRequirements(co -> {
  turret.atTarget.onTrue(shooter.shootOnce());
  co.await(turret.lockOnGoal());
}).named("Shoot While Aiming");
controller.rightBumper().whileTrue(shootWhileAiming);

  • Constructor Summary

    Constructors
    Constructor
    Description
    Trigger(BooleanSupplier condition)
    Creates a new trigger based on the given condition.
    Trigger(Scheduler scheduler, BooleanSupplier condition)
    Creates a new trigger based on the given condition.
    Trigger(Scheduler scheduler, EventLoop loop, BooleanSupplier condition)
    Creates a new trigger based on the given condition.

  • Method Summary

    Modifier and Type
    Method
    Description
    Trigger
    and(BooleanSupplier trigger)
    Composes two triggers with logical AND.
    Trigger
    debounce(Time duration)
    Creates a new debounced trigger from this trigger - it will become active when this trigger has been active for longer than the specified period.
    Trigger
    debounce(Time duration, Debouncer.DebounceType type)
    Creates a new debounced trigger from this trigger - it will become active when this trigger has been active for longer than the specified period.
    Trigger
    fallingEdge()
    Creates a trigger that activates on a falling edge of this trigger's signal.
    boolean
    getAsBoolean()
    Gets the boolean state of the trigger.
    Trigger
    multiPress(int pressCount, Time duration)
    Creates a trigger that activates when this trigger has at least pressCount rising edges within the specified duration.
    Trigger
    negate()
    Creates a new trigger that is active when this trigger is inactive, i.e.
    Trigger
    onFalse(Command command)
    Starts the given command whenever the condition changes from `true` to `false`.
    Trigger
    onTrue(Command command)
    Starts the given command whenever the condition changes from `false` to `true`.
    Trigger
    or(BooleanSupplier trigger)
    Composes two triggers with logical OR.
    Trigger
    retryWhileFalse(Command command)
    Starts the given command when the condition changes to `false` and cancels it when the condition changes to `true`.
    Trigger
    retryWhileTrue(Command command)
    Starts the given command when the condition changes to `true` and cancels it when the condition changes to `false`.
    Trigger
    risingEdge()
    Creates a trigger that activates on a rising edge of this trigger's signal.
    Trigger
    toggleOnFalse(Command command)
    Toggles a command when the condition changes from `true` to `false`.
    Trigger
    toggleOnTrue(Command command)
    Toggles a command when the condition changes from `false` to `true`.
    void
    unbind()
    Unbinds this trigger from the event loop and clears all command bindings; any bound commands that are currently running will be canceled.
    Trigger
    whileFalse(Command command)
    Starts the given command when the condition changes to `false` and cancels it when the condition changes to `true`.
    Trigger
    whileTrue(Command command)
    Starts the given command when the condition changes to `true` and cancels it when the condition changes to `false`.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Trigger

      public Trigger(Scheduler scheduler, BooleanSupplier condition)
      Creates a new trigger based on the given condition. Polled by the scheduler's default event loop.
      Parameters:
      scheduler - The scheduler that should execute triggered commands.
      condition - the condition represented by this trigger

    • Trigger

      public Trigger(BooleanSupplier condition)
      Creates a new trigger based on the given condition. Triggered commands are executed by the default scheduler.

      Polled by the default scheduler button loop.

      Parameters:
      condition - the condition represented by this trigger

    • Trigger

      public Trigger(Scheduler scheduler, EventLoop loop, BooleanSupplier condition)
      Creates a new trigger based on the given condition.
      Parameters:
      scheduler - The scheduler that should execute triggered commands.
      loop - The event loop to poll the trigger.
      condition - the condition represented by this trigger

  • Method Details

    • onTrue

      public Trigger onTrue(Command command)
      Starts the given command whenever the condition changes from `false` to `true`.
      Parameters:
      command - the command to start
      Returns:
      this trigger, so calls can be chained

    • onFalse

      public Trigger onFalse(Command command)
      Starts the given command whenever the condition changes from `true` to `false`.
      Parameters:
      command - the command to start
      Returns:
      this trigger, so calls can be chained

    • whileTrue

      public Trigger whileTrue(Command command)
      Starts the given command when the condition changes to `true` and cancels it when the condition changes to `false`.

      Unlike retryWhileTrue(Command), this does not restart the command if it ends while the condition is still `true`.

      Parameters:
      command - the command to start
      Returns:
      this trigger, so calls can be chained

    • whileFalse

      public Trigger whileFalse(Command command)
      Starts the given command when the condition changes to `false` and cancels it when the condition changes to `true`.

      Unlike retryWhileFalse(Command), this does not restart the command if it ends while the condition is still `false`.

      Parameters:
      command - the command to start
      Returns:
      this trigger, so calls can be chained

    • retryWhileTrue

      public Trigger retryWhileTrue(Command command)
      Starts the given command when the condition changes to `true` and cancels it when the condition changes to `false`.

      Unlike whileTrue(Command), the command is restarted if it ends while the condition is still `true`. If the command stopped because it was interrupted, restarting it will immediately interrupt the would-be interrupting command (if they have the same priority).

      Parameters:
      command - the command to start
      Returns:
      this trigger, so calls can be chained

    • retryWhileFalse

      public Trigger retryWhileFalse(Command command)
      Starts the given command when the condition changes to `false` and cancels it when the condition changes to `true`.

      Unlike whileFalse(Command), the command is restarted if it ends while the condition is still `false`. If the command stopped because it was interrupted, restarting it will immediately interrupt the would-be interrupting command (if they have the same priority).

      Parameters:
      command - the command to start
      Returns:
      this trigger, so calls can be chained

    • toggleOnTrue

      public Trigger toggleOnTrue(Command command)
      Toggles a command when the condition changes from `false` to `true`.
      Parameters:
      command - the command to toggle
      Returns:
      this trigger, so calls can be chained

    • toggleOnFalse

      public Trigger toggleOnFalse(Command command)
      Toggles a command when the condition changes from `true` to `false`.
      Parameters:
      command - the command to toggle
      Returns:
      this trigger, so calls can be chained

    • getAsBoolean

      public boolean getAsBoolean()
      Gets the boolean state of the trigger. Because triggers are checked when their event loop is polled, which by default occurs when Scheduler.run() is called in user code, but may differ for custom event loops, the state is only valid immediately after the event loop is polled. If the underlying signal changes without a subsequent event loop poll, the return value from getAsBoolean() may not agree with the result of checking the signal directly.

      This method will always return false before being polled by an event loop.

      Specified by:
      getAsBoolean in interface BooleanSupplier
      Returns:
      The state of the trigger.

    • and

      public Trigger and(BooleanSupplier trigger)
      Composes two triggers with logical AND.
      Parameters:
      trigger - the condition to compose with
      Returns:
      A trigger which is active when both component triggers are active.

    • or

      public Trigger or(BooleanSupplier trigger)
      Composes two triggers with logical OR.
      Parameters:
      trigger - the condition to compose with
      Returns:
      A trigger which is active when either component trigger is active.

    • negate

      public Trigger negate()
      Creates a new trigger that is active when this trigger is inactive, i.e. that acts as the negation of this trigger.
      Returns:
      the negated trigger

    • debounce

      public Trigger debounce(Time duration)
      Creates a new debounced trigger from this trigger - it will become active when this trigger has been active for longer than the specified period.
      Parameters:
      duration - The debounce period.
      Returns:
      The debounced trigger (rising edges debounced only)

    • debounce

      public Trigger debounce(Time duration, Debouncer.DebounceType type)
      Creates a new debounced trigger from this trigger - it will become active when this trigger has been active for longer than the specified period.
      Parameters:
      duration - The debounce period.
      type - The debounce type.
      Returns:
      The debounced trigger.

    • risingEdge

      public Trigger risingEdge()
      Creates a trigger that activates on a rising edge of this trigger's signal. The rising edge trigger is active in the same cycle that this trigger's condition is true while its condition in the previous cycle was false. The resulting trigger will only be active for that single cycle before going inactive again; therefore, onTrue(Command) should be used instead of whileTrue(Command), as commands bound using the latter method will be immediately canceled after a single scheduler cycle.
      Returns:
      A rising edge trigger.

    • fallingEdge

      public Trigger fallingEdge()
      Creates a trigger that activates on a falling edge of this trigger's signal. The falling edge trigger is active in the same cycle that this trigger's condition is false while its condition in the previous cycle was true. The resulting trigger will only be active for that single cycle before going inactive again; therefore, onTrue(Command) should be used instead of whileTrue(Command), as commands bound using the latter method will be immediately canceled after a single scheduler cycle.
      Returns:
      A falling edge trigger.

    • multiPress

      public Trigger multiPress(int pressCount, Time duration)
      Creates a trigger that activates when this trigger has at least pressCount rising edges within the specified duration.
      Parameters:
      pressCount - The number of rising edges to require. If this is non-positive, the trigger will always be active.
      duration - The duration within which the rising edges must occur. If this is non-positive, the trigger will never activate.
      Returns:
      A trigger that activates on multiple presses

    • unbind

      public void unbind()
      Unbinds this trigger from the event loop and clears all command bindings; any bound commands that are currently running will be canceled. The trigger may be garbage collected if no other references exist in user code. Binding a command to a trigger via onTrue(Command) or similar will re-bind the trigger to the event loop.

      Note: because triggers are only updated when they're bound to an event loop, calling #unbind() will result in getAsBoolean() continuing to return the same value until the trigger is re-bound.

      This method is automatically called by the associated Scheduler when the trigger's creation scope becomes inactive: a trigger created inside a command will be unbound when that command completes, and may be eligible for garbage collection; and a trigger created while an opmode is running will be unbound when that opmode ends (and also may be eligible for garbage collection).