3 * Interface definition for encapsulated commands.
4 * Started Spring 2001 by David Megginson, david@megginson.com
5 * This code is released into the Public Domain.
10 #ifndef __COMMANDS_HXX
11 #define __COMMANDS_HXX
14 #include <simgear/compiler.h>
30 * <p>This class allows the application to register and unregister
31 * commands, and provides shortcuts for executing them. Commands
32 * are simple functions that take a const pointer to an SGPropertyNode
33 * as an argument and return a bool value indicating success or failure.
34 * The property node may be ignored, or it may contain values that
35 * the command uses as parameters.</p>
37 * <p>There are convenience methods for invoking a command function
38 * with no arguments or with a single, primitive argument.</p>
40 * @author David Megginson, david@megginson.com
47 * Type for a command function.
49 typedef bool (*command_t) (const SGPropertyNode * arg);
53 * Default constructor.
61 virtual ~SGCommandMgr ();
65 * Register a new command with the manager.
67 * @param name The command name. Any existing command with
68 * the same name will silently be overwritten.
69 * @param command A pointer to a one-arg function returning
70 * a bool result. The argument is always a const pointer to
71 * an SGPropertyNode (which may contain multiple values).
73 virtual void addCommand (const string &name, command_t command);
77 * Look up an existing command.
79 * @param name The command name.
80 * @return A pointer to the command, or 0 if there is no registered
81 * command with the name specified.
83 virtual command_t getCommand (const string &name) const;
87 * Get a list of all existing command names.
89 * @return A (possibly empty) vector of the names of all registered
92 virtual vector<string> getCommandNames () const;
98 * This is the primary method for invoking a command; the others
99 * are convenience methods that invoke this one indirectly.
101 * @param name The name of the command.
102 * @param arg A const pointer to an SGPropertyNode. The node
103 * may have a value and/or children, etc., so that it is possible
104 * to pass an arbitrarily complex data structure to a command.
105 * @return true if the command is present and executes successfully,
108 virtual bool execute (const string &name, const SGPropertyNode * arg) const;
112 * Execute a command with no argument.
114 * The command function will receive a pointer to a property node
115 * with no value and no children.
117 * @param name The name of the command.
118 * @return true if the command is present and executes successfully,
121 virtual bool execute (const string &name) const;
125 * Execute a command with a single bool argument.
127 * The command function will receive a pointer to a property node
128 * with a bool value and no children.
130 * @param name The name of the command.
131 * @param arg The bool argument to the command.
132 * @return true if the command is present and executes successfully,
135 virtual bool execute (const string &name, bool arg) const;
139 * Execute a command with a single int argument.
141 * The command function will receive a pointer to a property node
142 * with a int value and no children.
144 * @param name The name of the command.
145 * @param arg The int argument to the command.
146 * @return true if the command is present and executes successfully,
149 virtual bool execute (const string &name, int arg) const;
153 * Execute a command with a single long argument.
155 * The command function will receive a pointer to a property node
156 * with a long value and no children.
158 * @param name The name of the command.
159 * @param arg The long argument to the command.
160 * @return true if the command is present and executes successfully,
163 virtual bool execute (const string &name, long arg) const;
167 * Execute a command with a single float argument.
169 * The command function will receive a pointer to a property node
170 * with a float value and no children.
172 * @param name The name of the command.
173 * @param arg The float argument to the command.
174 * @return true if the command is present and executes successfully,
177 virtual bool execute (const string &name, float arg) const;
181 * Execute a command with a single double argument.
183 * The command function will receive a pointer to a property node
184 * with a double value and no children.
186 * @param name The name of the command.
187 * @param arg The double argument to the command.
188 * @return true if the command is present and executes successfully,
191 virtual bool execute (const string &name, double arg) const;
195 * Execute a command with a single string argument.
197 * The command function will receive a pointer to a property node
198 * with a string value and no children.
200 * @param name The name of the command.
201 * @param arg The string argument to the command.
202 * @return true if the command is present and executes successfully,
205 virtual bool execute (const string &name, string arg) const;
210 typedef map<string,command_t> command_map;
211 command_map _commands;
215 #endif __COMMANDS_HXX
217 // end of commands.hxx