WPILibC++  2019.3.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
frc::Command Class Referenceabstract

The Command class is at the very core of the entire command framework. More...

#include <Command.h>

Inheritance diagram for frc::Command:
frc::ErrorBase frc::SendableBase frc::Sendable frc::CommandGroup frc::ConditionalCommand frc::InstantCommand frc::PIDCommand frc::TimedCommand frc::WaitForChildren frc::WaitUntilCommand frc::PrintCommand frc::StartCommand frc::WaitCommand

Public Types

using SubsystemSet = wpi::SmallPtrSetImpl< Subsystem * >
 

Public Member Functions

 Command ()
 Creates a new command. More...
 
 Command (const wpi::Twine &name)
 Creates a new command with the given name and no timeout. More...
 
 Command (double timeout)
 Creates a new command with the given timeout and a default name. More...
 
 Command (Subsystem &subsystem)
 Creates a new command with the given timeout and a default name. More...
 
 Command (const wpi::Twine &name, double timeout)
 Creates a new command with the given name and timeout. More...
 
 Command (const wpi::Twine &name, Subsystem &subsystem)
 Creates a new command with the given name and timeout. More...
 
 Command (double timeout, Subsystem &subsystem)
 Creates a new command with the given name and timeout. More...
 
 Command (const wpi::Twine &name, double timeout, Subsystem &subsystem)
 Creates a new command with the given name and timeout. More...
 
 Command (Command &&)=default
 
Commandoperator= (Command &&)=default
 
double TimeSinceInitialized () const
 Returns the time since this command was initialized (in seconds). More...
 
void Requires (Subsystem *s)
 This method specifies that the given Subsystem is used by this command. More...
 
void Start ()
 Starts up the command. More...
 
bool Run ()
 The run method is used internally to actually run the commands. More...
 
void Cancel ()
 This will cancel the current command. More...
 
bool IsRunning () const
 Returns whether or not the command is running. More...
 
bool IsInitialized () const
 Returns whether or not the command has been initialized. More...
 
bool IsCompleted () const
 Returns whether or not the command has completed running. More...
 
bool IsCanceled () const
 Returns whether or not this has been canceled. More...
 
bool IsInterruptible () const
 Returns whether or not this command can be interrupted. More...
 
void SetInterruptible (bool interruptible)
 Sets whether or not this command can be interrupted. More...
 
bool DoesRequire (Subsystem *subsystem) const
 Checks if the command requires the given Subsystem. More...
 
const SubsystemSetGetRequirements () const
 Returns the requirements (as an std::set of Subsystem pointers) of this command. More...
 
CommandGroupGetGroup () const
 Returns the CommandGroup that this command is a part of. More...
 
void SetRunWhenDisabled (bool run)
 Sets whether or not this Command should run when the robot is disabled. More...
 
bool WillRunWhenDisabled () const
 Returns whether or not this Command will run when the robot is disabled, or if it will cancel itself. More...
 
int GetID () const
 Get the ID (sequence number) for this command. More...
 
void InitSendable (SendableBuilder &builder) override
 Initializes this Sendable object. More...
 
- Public Member Functions inherited from frc::ErrorBase
 ErrorBase (ErrorBase &&)=default
 
ErrorBaseoperator= (ErrorBase &&)=default
 
virtual ErrorGetError ()
 Retrieve the current error. More...
 
virtual const ErrorGetError () const
 Retrieve the current error. More...
 
virtual void ClearError () const
 Clear the current error information associated with this sensor.
 
virtual void SetErrnoError (const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber) const
 Set error information associated with a C library call that set an error to the "errno" global variable. More...
 
virtual void SetImaqError (int success, const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber) const
 Set the current error information associated from the nivision Imaq API. More...
 
virtual void SetError (Error::Code code, const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber) const
 Set the current error information associated with this sensor. More...
 
virtual void SetErrorRange (Error::Code code, int32_t minRange, int32_t maxRange, int32_t requestedValue, const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber) const
 Set the current error information associated with this sensor. More...
 
virtual void SetWPIError (const wpi::Twine &errorMessage, Error::Code code, const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber) const
 Set the current error information associated with this sensor. More...
 
virtual void CloneError (const ErrorBase &rhs) const
 
virtual bool StatusIsFatal () const
 Check if the current error code represents a fatal error. More...
 
- Public Member Functions inherited from frc::SendableBase
 SendableBase (bool addLiveWindow=true)
 Creates an instance of the sensor base. More...
 
 SendableBase (SendableBase &&rhs)
 
SendableBaseoperator= (SendableBase &&rhs)
 
std::string GetName () const final
 Gets the name of this Sendable object. More...
 
void SetName (const wpi::Twine &name) final
 Sets the name of this Sendable object. More...
 
std::string GetSubsystem () const final
 Gets the subsystem name of this Sendable object. More...
 
void SetSubsystem (const wpi::Twine &subsystem) final
 Sets the subsystem name of this Sendable object. More...
 
- Public Member Functions inherited from frc::Sendable
 Sendable (Sendable &&)=default
 
Sendableoperator= (Sendable &&)=default
 
void SetName (const wpi::Twine &subsystem, const wpi::Twine &name)
 Sets both the subsystem name and device name of this Sendable object. More...
 

Protected Member Functions

void SetTimeout (double timeout)
 Sets the timeout of this command. More...
 
bool IsTimedOut () const
 Returns whether or not the TimeSinceInitialized() method returns a number which is greater than or equal to the timeout for the command. More...
 
bool AssertUnlocked (const std::string &message)
 If changes are locked, then this will generate a CommandIllegalUse error. More...
 
void SetParent (CommandGroup *parent)
 Sets the parent of this command. More...
 
bool IsParented () const
 Returns whether the command has a parent. More...
 
void ClearRequirements ()
 Clears list of subsystem requirements. More...
 
virtual void Initialize ()
 The initialize method is called the first time this Command is run after being started.
 
virtual void Execute ()
 The execute method is called repeatedly until this Command either finishes or is canceled.
 
virtual bool IsFinished ()=0
 Returns whether this command is finished. More...
 
virtual void End ()
 Called when the command ended peacefully. More...
 
virtual 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. More...
 
virtual void _Initialize ()
 
virtual void _Interrupted ()
 
virtual void _Execute ()
 
virtual void _End ()
 
virtual void _Cancel ()
 This works like Cancel(), except that it doesn't throw an exception if it is a part of a command group. More...
 
- Protected Member Functions inherited from frc::SendableBase
void AddChild (std::shared_ptr< Sendable > child)
 Add a child component. More...
 
void AddChild (void *child)
 Add a child component. More...
 
void SetName (const wpi::Twine &moduleType, int channel)
 Sets the name of the sensor with a channel number. More...
 
void SetName (const wpi::Twine &moduleType, int moduleNumber, int channel)
 Sets the name of the sensor with a module and channel number. More...
 

Friends

class CommandGroup
 
class Scheduler
 
class ConditionalCommand
 

Additional Inherited Members

- Static Public Member Functions inherited from frc::ErrorBase
static void SetGlobalError (Error::Code code, const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber)
 
static void SetGlobalWPIError (const wpi::Twine &errorMessage, const wpi::Twine &contextMessage, wpi::StringRef filename, wpi::StringRef function, int lineNumber)
 
static const ErrorGetGlobalError ()
 Retrieve the current global error.
 
- Protected Attributes inherited from frc::ErrorBase
Error m_error
 

Detailed Description

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
CommandGroup
Subsystem

Constructor & Destructor Documentation

frc::Command::Command ( )

Creates a new command.

The name of this command will be default.

frc::Command::Command ( const wpi::Twine name)
explicit

Creates a new command with the given name and no timeout.

Parameters
namethe name for this command
frc::Command::Command ( double  timeout)
explicit

Creates a new command with the given timeout and a default name.

Parameters
timeoutthe time (in seconds) before this command "times out"
See also
IsTimedOut()
frc::Command::Command ( Subsystem subsystem)
explicit

Creates a new command with the given timeout and a default name.

Parameters
subsystemthe subsystem that the command requires
frc::Command::Command ( const wpi::Twine name,
double  timeout 
)

Creates a new command with the given name and timeout.

Parameters
namethe name of the command
timeoutthe time (in seconds) before this command "times out"
See also
IsTimedOut()
frc::Command::Command ( const wpi::Twine name,
Subsystem subsystem 
)

Creates a new command with the given name and timeout.

Parameters
namethe name of the command
subsystemthe subsystem that the command requires
frc::Command::Command ( double  timeout,
Subsystem subsystem 
)

Creates a new command with the given name and timeout.

Parameters
timeoutthe time (in seconds) before this command "times out"
subsystemthe subsystem that the command requires
See also
IsTimedOut()
frc::Command::Command ( const wpi::Twine name,
double  timeout,
Subsystem subsystem 
)

Creates a new command with the given name and timeout.

Parameters
namethe name of the command
timeoutthe time (in seconds) before this command "times out"
subsystemthe subsystem that the command requires
See also
IsTimedOut()

Member Function Documentation

virtual void frc::Command::_Cancel ( )
protectedvirtual

This works like Cancel(), except that it doesn't throw an exception if it is a part of a command group.

Should only be called by the parent command group.

Reimplemented in frc::ConditionalCommand.

bool frc::Command::AssertUnlocked ( const std::string &  message)
protected

If changes are locked, then this will generate a CommandIllegalUse error.

Parameters
messageThe message to report on error (it is appended by a default message)
Returns
True if assert passed, false if assert failed.
void frc::Command::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.

void frc::Command::ClearRequirements ( )
protected

Clears list of subsystem requirements.

This is only used by ConditionalCommand so cancelling the chosen command works properly in CommandGroup.

bool frc::Command::DoesRequire ( Subsystem subsystem) const

Checks if the command requires the given Subsystem.

Parameters
systemthe system
Returns
whether or not the subsystem is required (false if given nullptr)
virtual void frc::Command::End ( )
protectedvirtual

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.

Reimplemented in frc::CommandGroup.

CommandGroup* frc::Command::GetGroup ( ) const

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)
int frc::Command::GetID ( ) const

Get the ID (sequence number) for this command.

The ID is a unique sequence number that is incremented for each command.

Returns
The ID of this command
const SubsystemSet& frc::Command::GetRequirements ( ) const

Returns the requirements (as an std::set of Subsystem pointers) of this command.

Returns
The requirements (as an std::set of Subsystem pointers) of this command
void frc::Command::InitSendable ( SendableBuilder builder)
overridevirtual

Initializes this Sendable object.

Parameters
buildersendable builder

Implements frc::Sendable.

Reimplemented in frc::PIDCommand.

virtual void frc::Command::Interrupted ( )
protectedvirtual

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.

Reimplemented in frc::CommandGroup.

bool frc::Command::IsCanceled ( ) const

Returns whether or not this has been canceled.

Returns
whether or not this has been canceled
bool frc::Command::IsCompleted ( ) const

Returns whether or not the command has completed running.

Returns
whether or not the command has completed running.
virtual bool frc::Command::IsFinished ( )
protectedpure virtual

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()

Implemented in frc::CommandGroup, frc::InstantCommand, frc::ConditionalCommand, frc::TimedCommand, frc::WaitUntilCommand, and frc::WaitForChildren.

bool frc::Command::IsInitialized ( ) const

Returns whether or not the command has been initialized.

Returns
whether or not the command has been initialized.
bool frc::Command::IsInterruptible ( ) const

Returns whether or not this command can be interrupted.

Returns
whether or not this command can be interrupted
bool frc::Command::IsParented ( ) const
protected

Returns whether the command has a parent.

Parameters
Trueif the command has a parent.
bool frc::Command::IsRunning ( ) const

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
bool frc::Command::IsTimedOut ( ) const
protected

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
void frc::Command::Requires ( Subsystem s)

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
subsystemThe Subsystem required
See also
Subsystem
bool frc::Command::Run ( )

The run method is used internally to actually run the commands.

Returns
Whether or not the command should stay within the Scheduler.
void frc::Command::SetInterruptible ( bool  interruptible)

Sets whether or not this command can be interrupted.

Parameters
interruptiblewhether or not this command can be interrupted
void frc::Command::SetParent ( CommandGroup parent)
protected

Sets the parent of this command.

No actual change is made to the group.

Parameters
parentthe parent
void frc::Command::SetRunWhenDisabled ( bool  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
runWhether this command should run when the robot is disabled.
void frc::Command::SetTimeout ( double  timeout)
protected

Sets the timeout of this command.

Parameters
timeoutthe timeout (in seconds)
See also
IsTimedOut()
void frc::Command::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.

double frc::Command::TimeSinceInitialized ( ) const

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).
bool frc::Command::WillRunWhenDisabled ( ) const

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

Returns
Whether this Command will run when the robot is disabled, or if it will cancel itself.

The documentation for this class was generated from the following file: