Chapter 8 - Events

An event is a signal that something happened in one of your applets. Events can be triggered by the user clicking the mouse, moving the mouse, or pressing a key. Events can also be triggered by system changes or just about anything that happens to your applet.

As a programmer you can check for these events and then act appropriately to add functionality to your Java applets. For instance if you wanted to paint a dot where the user clicks you would check for the mouseDown() event and then paint a dot when it occurs.

Mouse events

Mouse events are caused when the user does something with the mouse. There are several methods you can override to provide actions based on these user inputs.

The mouseEnter() method is called when the mouse pointer enter the area of the screen where the applet is running. The mouseExit() method is called when the mouse pointer leaves the same area. This is useful for tracking the mouse during the life of the applet.

	public boolean mouseEnter(Event e, int x, int y) {
	}

	public boolean mouseExit(Event e, int x, int y) {
	}

The first parameter is the event itself which is useful to have in some cases. The values of x and y are the coordinates where the event occurred.

The mouseDown() method is called when the user clicks down on the mouse button while the mouseUp() method is called when the user releases the mouse button. So a single click of the mouse generates two separate events. This is useful because you may want to take different actions at the two different stages of a mouse click. The parameters have similar meaning to the above methods.

	public boolean mouseDown(Event e, int x, int y) {
	}

	public boolean mouseUp(Event e, int x, int y) {
	}

The mouseMove() and mouseDrag() event are called when the mouse pointer is moved inside the area of the running applet. The mouseDrag() method is called if the mouse button was also being depressed during the movement. The parameters are also the same as the above methods.

	public boolean mouseMove(Event e, int x, int y) {
	}

	public boolean mouseDrag(Event e, int x, int y) {
	}

If the user clicked in your applet and dragged to another point a series of events are recorded. First the mouse entered the applet at some point. The mouse then moved to the point where the click was going to occur which repeatedly calls mouseMove() for each pixel of distance. The user then pressed the mouse button which generates a mouseDown() event and drags the pointer to a new location which repeatedly calls the mouseDrag() method. At the end of the motion the user releases the mouse button and generates a mouseUp() event.

Keyboard events

Keyboard events are similar to mouse clicks. The keyDown() method is called when the user presses a key on the keyboard and the keyUp() method is called when the user releases that key.

	public boolean keyDown(Event e, int key) {
	}

	public boolean keyUp(Event e, int key) {
	}

The key is returned as the integer value of the ASCII representation of that key. This means that you can use these keys in switch statements to test for different keys. It also means that if you need to print the character you need to first change them into the type char from int. The Event class also provides several class variables for you to use so your code will be more readable.

	Event.DOWN			down arrow
	Event.UP			up arrow
	Event.LEFT			left arrow
	Event.RIGHT			right arrow
	Event.HOME			home key
	Event.END			end key
	Event.PGDN			page down key
	Event.PGUP			page up key
	Event.F#			the corresponding "F" key (where # is 1-12)

Your code can also test to see if modifier keys, such as shift, control, or command (meta), were held during the key event. The three methods shiftDown(), controlDown(), and metaDown(), all return boolean values that you can check in your code. They are used by calling them on the event you wish to check.

handleEvent() method

You can handle all the generic events much in the same way as the actions by using the handleEvent() method. You can override the method and test for various events to add functionality to your applet.

	public boolean handleEvent(Event e) {
	}

Testing for different events is done by checking the event ID. The ID is an integer which allows you to use the switch statement for testing. There are class variables defined that help your code be readable and are easier to remember.

	public boolean handleEvent(Event e) {
		if (e.id == Event.MOUSE_DOWN) {
			mouseIsDown(e, e.x, e.y);
			return true;
		}
		else if (e.id == Event.MOUSE_UP) {
			mouseIsUp(e, e.x, e.y);
			return true;
		}
		else return false;
	}

	public boolean handleEvent(Event e) {
		switch (e.id) {
			case Event.MOUSE_DOWN:
				mouseIsDown(e, e.x, e.y);
				return true;
			case Event.MOUSE_UP:
				mouseIsUp(e, e.x, e.y);
				return true;
			default:
				return false;
		}
	}

If you do override the handleEvent() method the default event methods you learned earlier will not be called. To overcome this, you can return super.handleEvent(e) at the end of the handleEvent() method.

Many events can be tested for in the handleEvent() method and have class variables defined for simplicity.

	Event.MOUSE_DOWN		mouse button is pressed
	Event.MOUSE_UP			mouse button is released
	Event.MOUSE_ENTER		mouse enters the applet
	Event.MOUSE_EXIT		mouse exits the applet
	Event.MOUSE_MOVE		mouse has been moved
	Event.MOUSE_DRAG		mouse has been moved with mouse button pressed
	Event.KEY_PRESS			key is pressed
	Event.KEY_RELEASE		key is released
	Event.KEY_ACTION		key is pressed and released (in text fields)
	Event.KEY_ACTION_RELEASE	????
	Event.SHIFT_MASK		the shift key was held during key event
	Event.CTRL_MASK			the control key was held during key event
	Event.META_MASK			the command key was held during key event
	Event.ALT_MASK			the option key was held during key event
	Event.ACTION_EVENT		action by UI component
	Event.LIST_SELECT		item selected in scrolling list
	Event.LIST_DESELECT		item deselected in scrolling list
	Event.SCROLL_ABSOLUTE		the scrollbar was moved
	Event.SCROLL_LINE_UP		top (or right) end button pushed in scrollbar
	Event.SCROLL_LINE_DOWN		bottom (or left) end button pushed in scrollbar
	Event.SCROLL_PAGE_UP		area above (or right) elevator is pressed
	Event.SCROLL_PAGE_DOWN		area below (or left) elevator is pressed
	Event.WINDOW_DESTROY		window is destroyed or closed
	Event.WINDOW_EXPOSE		window is brought to front
	Event.WINDOW_ICONIFY		window was iconified
	Event.WINDOW_DEICONIFY		window was deiconified
	Event.WINDOW_MOVED		window was moved
	Event.LOAD_FILE			a file was loaded
	Event.SAVE_FILE			a file was saved
	Event.GOT_FOCUS			a component gained focus
	Event.LOST_FOCUS		a component lost focus

UI actions

User Interface components generate events called actions and to capture these events you need to override the action() method. This method intercepts the actions generated by all the UI components so you need to test for the different types of actions. As other events, it is passed the event object that lets you easily reference it. The second argument is an object that passes extra information about the action that occurred.

	public boolean action(Event e, Object arg) {
	}

The instanceof operator is used to detect which kind of action was generated. It is also common to call a separate method to handle the action rather than defining the response in the action method itself.

	public boolean action(Event e, Object arg) {
		if (e.target instanceof Button)
			clickedButton(arg);
		else if (e.target instanceof Choice)
			menuChoice(arg);
		return true;
	}

Different UI components generate different actions and pass different objects.

	Button				argument is the button label
	Checkbox			argument is true
	Choice				argument is the item that was selected