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 typedef map<string,command_t> command_map;
156 command_map _commands;
160 #endif // __COMMANDS_HXX
162 // end of commands.hxx