annotate src/samer/core_/Agent.java @ 8:5e3cbbf173aa tip

Reorganise some more

/*
 *	Agent.java	
 *
 *	Copyright (c) 2000, Samer Abdallah, King's College London.
 *	All rights reserved.
 *
 *	This software is provided AS iS and WITHOUT ANY WARRANTY; 
 *	without even the implied warranty of MERCHANTABILITY or 
 *	FITNESS FOR A PARTICULAR PURPOSE.
 */

package samer.core;

/**
	An Agent is something that can handle commands.
	It can also optionally report which commands it
	can handle so that they can be exposed in some
	way, eg buttons or a menu.
 */

public interface Agent
{
	/**
		Bad interface name, I know, but a Registry is
		supplied to an agent so that it can report
		which commands it handles. The implementation
		of the Registry can do whatever it likes with
		the names: compile a list, create buttons or a
		menu, or just ignore them.

		<p>May eventually want to be able to supply
		more information abdut a command, so that we
		can, eg, put an icon on a toolbar or have a
		tool tip
	 */

	public interface Registry {
		Registry add( String name);

		/**
			The second form of add, with a boolean
			second argument suggests that the command expects
			a boolean argument and can thus be associated
			with a checkbox or check menu item.
		 */

		Registry add( String name, boolean initialValue);

		/** 
			This means that the following commands reported
			to add() are to be directed to a different Agent
		 */

		void     setTarget(Agent a);

		/** this means start a new group */
		void group(); 
	}

	/** Implementations can use the Registry to report which
		commands they respond to */
	void getCommands(Registry r);

	/** This must do what the named command says using the given Environment
		for parameters or supplimentary data. */
	void execute( String name, Environment env) throws Exception;
}