edu.wpi.first.wpilibj.command

## Class Command

- java.lang.Object
- - edu.wpi.first.wpilibj.command.Command

- All Implemented Interfaces:
    NamedSendable, Sendable
  Direct Known Subclasses:
    CommandGroup, ConditionalCommand, InstantCommand, PIDCommand, TimedCommand, WaitForChildren, WaitUntilCommand

      public abstract class Command
      extends java.lang.Object
      implements NamedSendable

  The Command class is at the very core of the entire command framework. Every command can be started with a call to `start()`. Once a command is started it will call `initialize()`, and then will repeatedly call `execute()` until the `isFinished()` returns true. Once it does, `end()` will be called.

  However, if at any point while it is running `cancel()` is called, then the command will be stopped and `interrupted()` will be called.

  If a command uses a `Subsystem`, then it should specify that it does so by calling the `requires(...)` method in its constructor. Note that a Command may have multiple requirements, and `requires(...)` should be called for each one.

  If a command is running and a new command with shared requirements is started, then one of two things will happen. If the active command is interruptible, then `cancel()` will be called and the command will be removed to make way for the new one. If the active command is not interruptible, the other one will not even be started, and the active one will continue functioning.

  See Also:
    `Subsystem`, `CommandGroup`, `IllegalUseOfCommandException`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Command()` Creates a new command.
    `Command(double timeout)` Creates a new command with the given timeout and a default name.
    `Command(java.lang.String name)` Creates a new command with the given name.
    `Command(java.lang.String name, double timeout)` Creates a new command with the given name and timeout.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cancel()` This will cancel the current command.
    `protected void` | `clearRequirements()` Clears list of subsystem requirements.
    `boolean` | `doesRequire(Subsystem system)` Checks if the command requires the given `Subsystem`.
    `protected void` | `end()` Called when the command ended peacefully.
    `protected void` | `execute()` The execute method is called repeatedly until this Command either finishes or is canceled.
    `CommandGroup` | `getGroup()` Returns the `CommandGroup` that this command is a part of.
    `java.lang.String` | `getName()` Returns the name of this command.
    `java.lang.String` | `getSmartDashboardType()` The string representation of the named data type that will be used by the smart dashboard for this `Sendable`.
    `protected void` | `initialize()` The initialize method is called the first time this Command is run after being started.
    `void` | `initTable(NetworkTable table)` Initializes a table for this `Sendable` object.
    `protected void` | `interrupted()` Called when the command ends because somebody called `cancel()` or another command shared the same requirements as this one, and booted it out.
    `boolean` | `isCanceled()` Returns whether or not this has been canceled.
    `protected abstract boolean` | `isFinished()` Returns whether this command is finished.
    `boolean` | `isInterruptible()` Returns whether or not this command can be interrupted.
    `boolean` | `isRunning()` Returns whether or not the command is running.
    `protected boolean` | `isTimedOut()` Returns whether or not the `timeSinceInitialized()` method returns a number which is greater than or equal to the timeout for the command.
    `protected void` | `requires(Subsystem subsystem)` This method specifies that the given `Subsystem` is used by this command.
    `protected void` | `setInterruptible(boolean interruptible)` Sets whether or not this command can be interrupted.
    `void` | `setRunWhenDisabled(boolean run)` Sets whether or not this `Command` should run when the robot is disabled.
    `protected void` | `setTimeout(double seconds)` Sets the timeout of this command.
    `void` | `start()` Starts up the command.
    `double` | `timeSinceInitialized()` Returns the time since this command was initialized (in seconds).
    `java.lang.String` | `toString()` The string representation for a `Command` is by default its name.
    `boolean` | `willRunWhenDisabled()` Returns whether or not this `Command` will run when the robot is disabled, or if it will cancel itself.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Command

          public Command()

      Creates a new command. The name of this command will be set to its class name.

    - #### Command

          public Command(java.lang.String name)

      Creates a new command with the given name.
      Parameters:
        `name` - the name for this command
      Throws:
        `java.lang.IllegalArgumentException` - if name is null

    - #### Command

          public Command(double timeout)

      Creates a new command with the given timeout and a default name. The default name is the name of the class.
      Parameters:
        `timeout` - the time (in seconds) before this command "times out"
      Throws:
        `java.lang.IllegalArgumentException` - if given a negative timeout
      See Also:
        `isTimedOut()`

    - #### Command

          public Command(java.lang.String name,
                         double timeout)

      Creates a new command with the given name and timeout.
      Parameters:
        `name` - the name of the command
        `timeout` - the time (in seconds) before this command "times out"
      Throws:
        `java.lang.IllegalArgumentException` - if given a negative timeout or name was null.
      See Also:
        `isTimedOut()`

  - ### Method Detail

    - #### getName

          public java.lang.String getName()

      Returns the name of this command. If no name was specified in the constructor, then the default is the name of the class.
      Specified by:
        `getName` in interface `NamedSendable`
      Returns:
        the name of this command

    - #### setTimeout

          protected final void setTimeout(double seconds)

      Sets the timeout of this command.
      Parameters:
        `seconds` - the timeout (in seconds)
      Throws:
        `java.lang.IllegalArgumentException` - if seconds is negative
      See Also:
        `isTimedOut()`

    - #### timeSinceInitialized

          public final double timeSinceInitialized()

      Returns the time since this command was initialized (in seconds). This function will work even if there is no specified timeout.
      Returns:
        the time since this command was initialized (in seconds).

    - #### requires

          protected void requires(Subsystem subsystem)

      This method specifies that the given `Subsystem` is used by this command. This method is crucial to the functioning of the Command System in general.

      Note that the recommended way to call this method is in the constructor.

      Parameters:
        `subsystem` - the `Subsystem` required
      Throws:
        `java.lang.IllegalArgumentException` - if subsystem is null
        `IllegalUseOfCommandException` - if this command has started before or if it has been given to a `CommandGroup`
      See Also:
        `Subsystem`

    - #### initialize

          protected void initialize()

      The initialize method is called the first time this Command is run after being started.

    - #### execute

          protected void execute()

      The execute method is called repeatedly until this Command either finishes or is canceled.

    - #### isFinished

          protected abstract boolean isFinished()

      Returns whether this command is finished. If it is, then the command will be removed and `end()` will be called.

      It may be useful for a team to reference the `isTimedOut()` method for time-sensitive commands.

      Returning false will result in the command never ending automatically. It may still be cancelled manually or interrupted by another command. Returning true will result in the command executing once and finishing immediately. We recommend using `InstantCommand` for this.

      Returns:
        whether this command is finished.
      See Also:
        `isTimedOut()`

    - #### end

          protected void end()

      Called when the command ended peacefully. This is where you may want to wrap up loose ends, like shutting off a motor that was being used in the command.

    - #### interrupted

          protected void interrupted()

      Called when the command ends because somebody called `cancel()` or another command shared the same requirements as this one, and booted it out.

      This is where you may want to wrap up loose ends, like shutting off a motor that was being used in the command.

      Generally, it is useful to simply call the `end()` method within this method, as done here.

    - #### isTimedOut

          protected boolean isTimedOut()

      Returns whether or not the `timeSinceInitialized()` method returns a number which is greater than or equal to the timeout for the command. If there is no timeout, this will always return false.
      Returns:
        whether the time has expired

    - #### clearRequirements

          protected void clearRequirements()

      Clears list of subsystem requirements. This is only used by `ConditionalCommand` so cancelling the chosen command works properly in `CommandGroup`.

    - #### start

          public void start()

      Starts up the command. Gets the command ready to start.

      Note that the command will eventually start, however it will not necessarily do so immediately, and may in fact be canceled before initialize is even called.

      Throws:
        `IllegalUseOfCommandException` - if the command is a part of a CommandGroup

    - #### isRunning

          public boolean isRunning()

      Returns whether or not the command is running. This may return true even if the command has just been canceled, as it may not have yet called `interrupted()`.
      Returns:
        whether or not the command is running

    - #### cancel

          public void cancel()

      This will cancel the current command.

      This will cancel the current command eventually. It can be called multiple times. And it can be called when the command is not running. If the command is running though, then the command will be marked as canceled and eventually removed.

      A command can not be canceled if it is a part of a command group, you must cancel the command group instead.

      Throws:
        `IllegalUseOfCommandException` - if this command is a part of a command group

    - #### isCanceled

          public boolean isCanceled()

      Returns whether or not this has been canceled.
      Returns:
        whether or not this has been canceled

    - #### isInterruptible

          public boolean isInterruptible()

      Returns whether or not this command can be interrupted.
      Returns:
        whether or not this command can be interrupted

    - #### setInterruptible

          protected void setInterruptible(boolean interruptible)

      Sets whether or not this command can be interrupted.
      Parameters:
        `interruptible` - whether or not this command can be interrupted

    - #### doesRequire

          public boolean doesRequire(Subsystem system)

      Checks if the command requires the given `Subsystem`.
      Parameters:
        `system` - the system
      Returns:
        whether or not the subsystem is required, or false if given null

    - #### getGroup

          public CommandGroup getGroup()

      Returns the `CommandGroup` that this command is a part of. Will return null if this `Command` is not in a group.
      Returns:
        the `CommandGroup` that this command is a part of (or null if not in group)

    - #### setRunWhenDisabled

          public void setRunWhenDisabled(boolean run)

      Sets whether or not this `Command` should run when the robot is disabled.

      By default a command will not run when the robot is disabled, and will in fact be canceled.

      Parameters:
        `run` - whether or not this command should run when the robot is disabled

    - #### willRunWhenDisabled

          public boolean willRunWhenDisabled()

      Returns whether or not this `Command` will run when the robot is disabled, or if it will cancel itself.
      Returns:
        True if this command will run when the robot is disabled.

    - #### toString

          public java.lang.String toString()

      The string representation for a `Command` is by default its name.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the string representation of this object

    - #### getSmartDashboardType

          public java.lang.String getSmartDashboardType()

      Description copied from interface: `Sendable`
      The string representation of the named data type that will be used by the smart dashboard for this `Sendable`.
      Specified by:
        `getSmartDashboardType` in interface `Sendable`
      Returns:
        The type of this `Sendable`.

    - #### initTable

          public void initTable(NetworkTable table)

      Description copied from interface: `Sendable`
      Initializes a table for this `Sendable` object.
      Specified by:
        `initTable` in interface `Sendable`
      Parameters:
        `table` - The table to put the values in.