/* A highly commented version of QTest.java, an applet/application for
 * testing the Queue class
 *
 * Written by Paul Chew for CS410, March 1997.
 * Modified by Paul Chew for CS410, January 1998.
 */

/* Each import statement causes a single public class to be available
 * from the named package.  The version below, with a * as the name of the
 * class, is a special syntax for importing all the public classes of the
 * java.awt package.  Without the import statement we could still use
 * the public classes of this package, but we would have to use the
 * fully qualified names (e.g., java.awt.Panel instead of just Panel).
 */
import java.awt.*;

/* Comments that start with "/**" are documentation commments that can
 * be used to automatically create code documentation.  Such comments
 * can (and should) be used before classes and methods.  The comment should
 * begin with a simple one sentence summary of the class or method; this
 * single sentence appears by itself in the documentation.  Any additional 
 * sentences expanding on the single summary sentence, are included in a 
 * later portion of the documentation.
 *
 * The following tags, when they appear at the beginning of a comment line
 * within a documentation comment, generate additional documentation: @see,
 * @author, @version, @param, @return, @exception.  It's a good idea to use
 * the last three even when you don't plan to produce separate documentation.
 */
/**
 * QTest - tests the Queue class.  Can be run as an applet or as a 
 * standalone application.
 * @author Paul Chew
 * @see Queue.java
 */
public class QTest extends java.applet.Applet
{
	/* For QTest to be able to run as an applet it must be a subclass of
	 * java.applet.Applet.
	 */

	/* Field and method declarations follow.  Access to both fields
	 * and methods is controlled by the keywords public, protected, and
	 * private.  Here's a table descrbing the various levels of access:
	 *
	 *				class		subclass	package		world
	 *	private			X
	 *	"friendly"		X						X
	 *	protected		X			X*			X
	 *	public			X			X			X			X
	 *
	 * "Friendly" is the access method used when nothing else is specified.
	 * The one entry has a * because a subclass can access a protected
	 * field of a class, but only its own copy. 
	 */

	/* A field or method can also be static or final.  A static field or
	 * method is associated with the class itself rather than an instance
	 * of that class.  A final method cannot be overridden.  
	 * A final field is constant; it cannot be assigned to.  By convention
	 * constants are written entirely in uppercase.  Note that Java
	 * is case-sensitive.
	 */

	/* q and qDisplay are accesible only from within this class.
	 */
	private Queue q = new Queue();			// Our Queue.
	private Label qDisplay;					// Displays queue's contents.
	
	/* This is a constructor.  The name of a constructor matches the name
	 * of its class.  Constructors have a different syntax than other methods.
	 * Note that there is no return type and that there is no return statement
	 * within the code.
	 *
	 * A constructor implicitly creates an instance of this class as its
	 * first action.  The rest of the code should assign values to the
	 * variables of this instance.  If no constructor is specified then
	 * a default constructor is used; it takes no arguments.
	 *
	 * A constructor is called with a special syntax using the keyword `new'.
	 */
	/**
	 * Constructor for our applet.
	 */
	public QTest () 
	{
		setBackground(Color.green);			// Background color.
		setLayout(new BorderLayout());		// Placement scheme.

		/* setLayout is used to specify how controls are layed out within
		 * our applet's space.  BorderLayout allows us to place items in any
		 * of 5 positions: "North", "South", "East", "West", and "Center".
		 */

		/* A Panel can be thought of as a simple box used to group things.
		*/
		// Panel for inserting.
		Panel ip = new Panel();
		ip.setBackground(Color.gray);
		ip.add(new Button("jan")); 
		ip.add(new Button("feb")); 
		ip.add(new Button("mar")); 
		ip.add(new Button("apr")); 
		ip.add(new Button("may")); 
		ip.add(new Button("jun")); 
		ip.add(new Button("jul"));
		ip.add(new Button("aug"));
		ip.add(new Button("sep"));
		ip.add(new Button("oct"));
		ip.add(new Button("nov"));
		ip.add(new Button("dec"));
		add("North",ip);
	
		// Panel for deleting.
		Panel dp = new Panel();
		dp.setBackground(Color.gray);
		dp.add(new Button("Get"));
		dp.add(new Button("Clear"));
		add("South",dp);

		// Display area.
		qDisplay = new Label(q.toString(),Label.CENTER);
		add("Center",qDisplay);
	}

	 
	/* When running a class as an application, the system looks for a method
	 * called `main'; it has to be declared as below (i.e., public static void
	 * and with an array of Strings for its parameter).  If no such method 
	 * exists then the program will not run.
	 */
	/** 
	 * The main() method acts as the applet's entry point when it is run
	 * as a standalone application. It is ignored if the applet is run from
	 * within an HTML page.
	 */
	public static void main(String args[])
	{
		Frame frame = new Frame();			// Create a window.
		frame.resize(600,200);				// Choose a size.
		frame.setTitle("Queue Window");		// Give it a title.
		QTest applet = new QTest();			// Create the applet.
		frame.add("Center",applet);			// Put the applet in the window.
		applet.init();						// Standard applet initializaion.
		applet.start();						// Standard applet start.
		frame.show();						// Make it visible.
	}


	/**
	 * Standard method for reporting information about an applet.
	 */
	public String getAppletInfo() 
	{
		return "Name: QTest\r\n" +
		       "Author: Paul Chew\r\n" +
		       "Created with Microsoft Visual J++ Version 1.0";
	}


	/* The method `action' is a standard method that we are overriding to
	 * get our buttons to work.  If we allow this method to return true then
	 * it indicates to the system that the event has been handled.  If we
	 * return false then the event will be passed on in the hope that some
	 * other class will take care of it.
	 */
	/**
	 * Standard method for handling control events.  This is where
	 * we can set things up to handle events generated by buttons
	 * or other standard controls.
	 * @param e the Event
	 * @param arg the Event's argument; for a Button this is the Button's name.
	 * @return true iff the Event has been handled.
	 */
	public boolean action (Event e, Object arg)
	{
		// If it's not a button then it's not ours to worry about.
		if (!(e.target instanceof Button)) return false;

		// For a button, arg here is the String that is the name of
		// the button.
		if ("Clear".equals(arg)) q.clear();
		else if ("Get".equals(arg))
		{
			if (!q.isEmpty()) q.get();
		}

		// Convert arg to String and put in Queue.
		else q.put((String)arg);
		
		// Whatever happened, we want to display the Queue's contents.
		qDisplay.setText(q.toString());
		return true;						// Indicates event has been handled.
	}


	/* Applets	have several methods that can be overridden to perform
	 * common tasks:
	 *
	 * public void init() is called when an applet is first loaded or
	 * reloaded.  Override this method to perform the initializations needed
	 * by your applet.
	 *
	 * public void start() is called when the page containing the applet
	 * first appears on the screen.
	 *
	 * public void stop() is called when the page containing the applet is
	 * no longer on the screen.
	 *
	 * public void destroy() is called when the applet is terminating.  
	 * Cleanup code goes here.
	 *
	 * public void paint(Graphics g) is called by the system whenever the 
	 * contents of your applet need to be painted or repainted.  Code for
	 * displaying your applet's contents goes here.  Note that the standard
	 * components handle their own painting.
	 */
}