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
28 * <p>This class allows the application to register and unregister
29 * commands, and provides shortcuts for executing them. Commands
30 * are simple functions that take a const pointer to an SGPropertyNode
31 * as an argument and return a bool value indicating success or failure.
32 * The property node may be ignored, or it may contain values that
33 * the command uses as parameters.</p>
35 * <p>There are convenience methods for invoking a command function
36 * with no arguments or with a single, primitive argument.</p>
38 * @author David Megginson, david@megginson.com
45 * Type for a command function.
47 typedef bool (*command_t) (const SGPropertyNode * arg);
51 * Default constructor.
59 virtual ~SGCommandMgr ();
63 * Register a new command with the manager.
65 * @param name The command name. Any existing command with
66 * the same name will silently be overwritten.
67 * @param command A pointer to a one-arg function returning
68 * a bool result. The argument is always a const pointer to
69 * an SGPropertyNode (which may contain multiple values).
71 virtual void addCommand (const string &name, command_t command);
75 * Look up an existing command.
77 * @param name The command name.
78 * @return A pointer to the command, or 0 if there is no registered
79 * command with the name specified.
81 virtual command_t getCommand (const string &name) const;
85 * Get a list of all existing command names.
87 * @return A (possibly empty) vector of the names of all registered
90 virtual vector<string> getCommandNames () const;
96 * This is the primary method for invoking a command; the others
97 * are convenience methods that invoke this one indirectly.
99 * @param name The name of the command.
100 * @param arg A const pointer to an SGPropertyNode. The node
101 * may have a value and/or children, etc., so that it is possible
102 * to pass an arbitrarily complex data structure to a command.
103 * @return true if the command is present and executes successfully,
106 virtual bool execute (const string &name, const SGPropertyNode * arg) const;
110 * Execute a command with no argument.
112 * The command function will receive a pointer to a property node
113 * with no value and no children.
115 * @param name The name of the command.
116 * @return true if the command is present and executes successfully,
119 virtual bool execute (const string &name) const;
123 * Execute a command with a single bool argument.
125 * The command function will receive a pointer to a property node
126 * with a bool value and no children.
128 * @param name The name of the command.
129 * @param arg The bool argument to the command.
130 * @return true if the command is present and executes successfully,
133 virtual bool execute (const string &name, bool arg) const;
137 * Execute a command with a single int argument.
139 * The command function will receive a pointer to a property node
140 * with a int value and no children.
142 * @param name The name of the command.
143 * @param arg The int argument to the command.
144 * @return true if the command is present and executes successfully,
147 virtual bool execute (const string &name, int arg) const;
151 * Execute a command with a single long argument.
153 * The command function will receive a pointer to a property node
154 * with a long value and no children.
156 * @param name The name of the command.
157 * @param arg The long argument to the command.
158 * @return true if the command is present and executes successfully,
161 virtual bool execute (const string &name, long arg) const;
165 * Execute a command with a single float argument.
167 * The command function will receive a pointer to a property node
168 * with a float value and no children.
170 * @param name The name of the command.
171 * @param arg The float argument to the command.
172 * @return true if the command is present and executes successfully,
175 virtual bool execute (const string &name, float arg) const;
179 * Execute a command with a single double argument.
181 * The command function will receive a pointer to a property node
182 * with a double value and no children.
184 * @param name The name of the command.
185 * @param arg The double argument to the command.
186 * @return true if the command is present and executes successfully,
189 virtual bool execute (const string &name, double arg) const;
193 * Execute a command with a single string argument.
195 * The command function will receive a pointer to a property node
196 * with a string value and no children.
198 * @param name The name of the command.
199 * @param arg The string argument to the command.
200 * @return true if the command is present and executes successfully,
203 virtual bool execute (const string &name, string arg) const;
208 typedef map<string,command_t> command_map;
209 command_map _commands;
213 #endif __COMMANDS_HXX
215 // end of commands.hxx