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>
28 * Stored state for a command.
30 * <p>This class allows a command to cache parts of its state between
31 * invocations with the same parameters. Nearly every command that
32 * actually uses this will subclass it in some way. The command
33 * allocates the structure, but it is up to the caller to delete it
34 * when it is no longer necessary, unless the command deletes it
35 * and replaces the value with 0 or another command-state object
38 * <p>Note that this class is for caching only; all of the information
39 * in it must be recoverable by other means, since the state could
40 * arbitrarily disappear between invocations if the caller decides to
43 * <p>By default, the command state includes a place to keep a copy of
46 * @author David Megginson, david@megginson.com
52 SGCommandState (const SGPropertyNode * args);
53 virtual ~SGCommandState ();
54 virtual void setArgs (const SGPropertyNode * args);
55 virtual const SGPropertyNode * getArgs () const { return _args; }
57 SGPropertyNode * _args;
64 * <p>This class allows the application to register and unregister
65 * commands, and provides shortcuts for executing them. Commands are
66 * simple functions that take a const pointer to an SGPropertyNode and
67 * a pointer to a pointer variable (which should be 0 initially) where
68 * the function can store compiled copies of its arguments, etc. to
69 * avoid expensive recalculations. If the command deletes the
70 * SGCommandState, it must replace it with a new pointer or 0;
71 * otherwise, the caller is free to delete and zero the pointer at any
72 * time and the command will start fresh with the next invocation.
73 * The command must return a bool value indicating success or failure.
74 * The property node may be ignored, or it may contain values that the
75 * command uses as parameters.</p>
77 * <p>There are convenience methods for invoking a command function
78 * with no arguments or with a single, primitive argument.</p>
80 * @author David Megginson, david@megginson.com
87 * Type for a command function.
89 typedef bool (*command_t) (const SGPropertyNode * arg,
90 SGCommandState ** state);
94 * Default constructor.
102 virtual ~SGCommandMgr ();
106 * Register a new command with the manager.
108 * @param name The command name. Any existing command with
109 * the same name will silently be overwritten.
110 * @param command A pointer to a one-arg function returning
111 * a bool result. The argument is always a const pointer to
112 * an SGPropertyNode (which may contain multiple values).
114 virtual void addCommand (const string &name, command_t command);
118 * Look up an existing command.
120 * @param name The command name.
121 * @return A pointer to the command, or 0 if there is no registered
122 * command with the name specified.
124 virtual command_t getCommand (const string &name) const;
128 * Get a list of all existing command names.
130 * @return A (possibly empty) vector of the names of all registered
133 virtual vector<string> getCommandNames () const;
139 * This is the primary method for invoking a command; the others
140 * are convenience methods that invoke this one indirectly.
142 * @param name The name of the command.
143 * @param arg A const pointer to an SGPropertyNode. The node
144 * may have a value and/or children, etc., so that it is possible
145 * to pass an arbitrarily complex data structure to a command.
146 * @return true if the command is present and executes successfully,
149 virtual bool execute (const string &name,
150 const SGPropertyNode * arg,
151 SGCommandState ** state) const;
155 // * Execute a command with no argument.
157 // * The command function will receive a pointer to a property node
158 // * with no value and no children.
160 // * @param name The name of the command.
161 // * @return true if the command is present and executes successfully,
162 // * false otherwise.
164 // virtual bool execute (const string &name) const;
168 // * Execute a command with a single bool argument.
170 // * The command function will receive a pointer to a property node
171 // * with a bool value and no children.
173 // * @param name The name of the command.
174 // * @param arg The bool argument to the command.
175 // * @return true if the command is present and executes successfully,
176 // * false otherwise.
178 // virtual bool execute (const string &name, bool arg) const;
182 // * Execute a command with a single int argument.
184 // * The command function will receive a pointer to a property node
185 // * with a int value and no children.
187 // * @param name The name of the command.
188 // * @param arg The int argument to the command.
189 // * @return true if the command is present and executes successfully,
190 // * false otherwise.
192 // virtual bool execute (const string &name, int arg) const;
196 // * Execute a command with a single long argument.
198 // * The command function will receive a pointer to a property node
199 // * with a long value and no children.
201 // * @param name The name of the command.
202 // * @param arg The long argument to the command.
203 // * @return true if the command is present and executes successfully,
204 // * false otherwise.
206 // virtual bool execute (const string &name, long arg) const;
210 // * Execute a command with a single float argument.
212 // * The command function will receive a pointer to a property node
213 // * with a float value and no children.
215 // * @param name The name of the command.
216 // * @param arg The float argument to the command.
217 // * @return true if the command is present and executes successfully,
218 // * false otherwise.
220 // virtual bool execute (const string &name, float arg) const;
224 // * Execute a command with a single double argument.
226 // * The command function will receive a pointer to a property node
227 // * with a double value and no children.
229 // * @param name The name of the command.
230 // * @param arg The double argument to the command.
231 // * @return true if the command is present and executes successfully,
232 // * false otherwise.
234 // virtual bool execute (const string &name, double arg) const;
238 // * Execute a command with a single string argument.
240 // * The command function will receive a pointer to a property node
241 // * with a string value and no children.
243 // * @param name The name of the command.
244 // * @param arg The string argument to the command.
245 // * @return true if the command is present and executes successfully,
246 // * false otherwise.
248 // virtual bool execute (const string &name, string arg) const;
253 typedef map<string,command_t> command_map;
254 command_map _commands;
258 #endif // __COMMANDS_HXX
260 // end of commands.hxx