sub_arctic.input
Class menu_focus_agent

java.lang.Object
  |
  +--sub_arctic.input.dispatch_agent
        |
        +--sub_arctic.input.focus_dispatch_agent
              |
              +--sub_arctic.input.menu_focus_agent

public class menu_focus_agent

extends focus_dispatch_agent

This agent handles the input during modal (pop-up or pull-down) menus. It is responsible for the sequencing so that submenus are popped down if a parent menu gets a selection. To use this agent, but sure that you use "add_to_focus" and that you add things in the logical order they are "popped up" on the display, i.e. submenus get added after parent menus.

This agent expects that you are going to pop up/down based when you get added to the focus set and when you get removed. Thus, when it thinks you should go away it just removes you from the focus set.

Field Summary

protected menu_notifier	_notify This is where we keep track of what object to notify when the interaction ends.
protected java.lang.reflect.Method	exit Hold a reference to the method object representing exit in our protocol.
protected java.lang.reflect.Method	feedback Hold a reference to the method object representing feeback in our input protocol.
protected menu_focusable	most_recent This holds the most recently active menu.
protected java.lang.reflect.Method	release Hold a reference to the method object representing release in our input protocol.

Fields inherited from class sub_arctic.input.focus_dispatch_agent

_focus_set, _user_info_set

Constructor Summary

menu_focus_agent()
Construct a new menu focus agent.

Method Summary

boolean	dispatch_event(event evt, java.lang.Object user_info, interactor to_obj, int seq_num) Send an event to the user's interactors.
boolean	event_is_useful(event evt) See if we even fool with this type of event.
protected menu_focusable	find_focused_item(event evt) This function is used to find a focused on item.
protected void	generate_exit_event(event evt, menu_focusable new_target, java.lang.Object user_info) This is used to generate an exit event whenever a focused on item is exited.
boolean	handle_notify_position(event evt) This is a function to allow us to determine if the object that popped up this menu wants to and in fact has changed the menu out from under us.
protected void	remove_children(event evt, menu_focusable mf) This does the work of determining if we need to remove children from the list of objects in the focus.
void	set_focus_to(focusable to_obj, event evt, java.lang.Object user_info) We override the set_focus_to method to make sure that if user code calls this we don't end up with a bogus value of notify.
void	set_focus_to(focusable to_obj, event evt, java.lang.Object user_info, menu_notifier notify) This is a special version of set_focus_to for the menu agent since frequently menus are popped up from some object which needs to be aware that the interaction has now ended.

Methods inherited from class sub_arctic.input.focus_dispatch_agent

add_to_focus, allowable_focus, clear_focus, focus_item, focus_set_size, inform_focus_enter, inform_focus_exit, is_in_focus, remove_from_focus, user_info_item

Methods inherited from class sub_arctic.input.dispatch_agent

after_dispatch_notify, dispatch_unused_event

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

feedback

protected java.lang.reflect.Method feedback

Hold a reference to the method object representing feeback in our input protocol.

exit

protected java.lang.reflect.Method exit

Hold a reference to the method object representing exit in our protocol.

release

protected java.lang.reflect.Method release

Hold a reference to the method object representing release in our input protocol.

most_recent

protected menu_focusable most_recent

This holds the most recently active menu. This allows us to send an "exit" command to him.

_notify

protected menu_notifier _notify

This is where we keep track of what object to notify when the interaction ends.

Constructor Detail

menu_focus_agent

public menu_focus_agent()

Construct a new menu focus agent.

Method Detail

event_is_useful

public boolean event_is_useful(event evt)

See if we even fool with this type of event. We only handle drag-related interactions.

Parameters:

event - evt the event to test

Returns:

boolean true if we want the event

Overrides:

event_is_useful in class dispatch_agent

dispatch_event

public boolean dispatch_event(event evt,
                              java.lang.Object user_info,
                              interactor to_obj,
                              int seq_num)

Send an event to the user's interactors.

Parameters:

event - evt the event to dispatch

interactor - to_obj the object to whom the event should go

Object - user_info the object the user provided at the time he entered the focus set

int - seq_num the sequence number of this event

Returns:

boolean we return true if we dispatched the event

Overrides:

dispatch_event in class focus_dispatch_agent

find_focused_item

protected menu_focusable find_focused_item(event evt)

This function is used to find a focused on item. If no focused on item is found, we return null, otherwise we return the focused on item.

Parameters:

event - evt the event we are checking

Returns:

menu_focusable the object on which we should be focused or null

generate_exit_event

protected void generate_exit_event(event evt,
                                   menu_focusable new_target,
                                   java.lang.Object user_info)

This is used to generate an exit event whenever a focused on item is exited. Note that you do NOT generate exit events unless the object being exited is the farther one along in the focus list. This is so that if you exit a menu item the wrong way (to the left) and then sweep around the menu with the mouse and enter the submenu, the submenu is there!

Parameters:

event - evt the event to dispatch

menu_focusable - new_target the newly entered object (since this object has been entered, we need to send an exit event to the previously most recent menu)

Object - user_info the object passed to this agent when this object entered the focus set

remove_children

protected void remove_children(event evt,
                               menu_focusable mf)

This does the work of determining if we need to remove children from the list of objects in the focus.

Parameters:

event - evt the event to be handled

menu_focusable - mf the object being checked for children who need to be removed

set_focus_to

public void set_focus_to(focusable to_obj,
                         event evt,
                         java.lang.Object user_info)

We override the set_focus_to method to make sure that if user code calls this we don't end up with a bogus value of notify.

Parameters:

focusable - to_obj the object to set the focus to

event - evt the event causing the focus change

Object - user_info the object to be passed back to to_obj during subsequent calls

Overrides:

set_focus_to in class focus_dispatch_agent

set_focus_to

public void set_focus_to(focusable to_obj,
                         event evt,
                         java.lang.Object user_info,
                         menu_notifier notify)

This is a special version of set_focus_to for the menu agent since frequently menus are popped up from some object which needs to be aware that the interaction has now ended. If you use this interface, the menu_button passed as notify will get a call on its menu_done() function to inform it that the interaction is complete.

Parameters:

focusable - to_obj the object to set the focus to

event - evt the event causing the focus change

Object - user_info the object to be passed back to to_obj during subsequent calls

menu_notify - notify the object to be notified when the interaction ends or possibly changes state

handle_notify_position

public boolean handle_notify_position(event evt)

This is a function to allow us to determine if the object that popped up this menu wants to and in fact has changed the menu out from under us.

Parameters:

event - evt the event to deal with

Returns:

boolean true if the notifier has put up a different menu