sub_arctic.input
Class move_drag_focus_agent

java.lang.Object
  |
  +--sub_arctic.input.dispatch_agent
        |
        +--sub_arctic.input.focus_dispatch_agent
              |
              +--sub_arctic.input.single_focus_agent
                    |
                    +--sub_arctic.input.move_drag_focus_agent

public class move_drag_focus_agent
extends single_focus_agent

Focus agent that implements move-drag. Move drag is a drag designed for moving objects around and is the most sophisticated of the drag protocols. The move_drag protocol provides for drag_start(), drag_feedback(), and drag_end() methods. The parameters passed to these supply an x,y position in the parent's coordinate system which can be used to directly set the position of the object being dragged.

Move-drag also implements a filtering (or limiting) process based on feature points of an object. Each object implements a set of feature points that represent interesting locations within it (by default these include the four corners and the center, plus the point at which the object was "grabbed" at the beginning of the drag). Move_drag_filters objects can can be used to modify the set of point that a designated feature point passes through. This is most often used to limit the allowable drag locations. For example, to limit the drag of an object to stay within the bounds of its parent. Note: base_interactor implements move_drag_filter, so often objects act as their own drag filter. std_drag_filters provides a useful collection of filter functions for this purpose.

See Also:
move_draggable, move_drag_filter, base_interactor.filter_pt(java.awt.Point, sub_arctic.lib.interactor, java.awt.Point), std_drag_filters

Field Summary
protected  int _drag_feature_point
          Index of the feature point we are dragging based on.
protected  move_drag_filter _filter_obj
          Object which acts as drag filter.
protected  java.lang.reflect.Method drag_end
          Hold a reference to the Method for drag_end
protected  java.lang.reflect.Method drag_feedback
          Hold a reference to the Method for drag_feedback
protected  java.lang.reflect.Method drag_start
          Hold a reference to the Method for drag_start
protected  int grab_x
          Grab x position (start position in local coordinates).
protected  int grab_y
          Grab y position (start position in local coordinates).
protected  int start_x
          Start x position of the current drag (in global coordinates)
protected  int start_y
          Start y position of the current drag (in global coordinates)
 
Fields inherited from class sub_arctic.input.focus_dispatch_agent
_focus_set, _user_info_set
 
Constructor Summary
move_drag_focus_agent()
          Default constructor
 
Method Summary
 boolean allowable_focus(focusable candidate_obj)
          Method to limit the objects allowable as members of the focus set.
 boolean dispatch_event(event evt, java.lang.Object user_info, interactor to_obj, int seq_num)
          Dispatch an event under this protocol.
 int drag_feature_point()
          Index of the feature point we are dragging based on.
 boolean event_is_useful(event evt)
          Method to determine if this agent needs to see a given event.
protected  java.awt.Point filter_drag_pt(interactor for_obj, java.awt.Point pt)
          Filter a drag point.
 move_drag_filter filter_obj()
          Object which acts as drag filter.
protected  void inform_focus_enter(focusable obj, event evt, java.lang.Object user_info)
          Override the normal inform_focus_enter to deliver the drag_start().
protected  void inform_focus_exit(focusable obj, event evt, java.lang.Object user_info)
          Override the normal inform_focus_exit to deliver the drag_end().
 void set_drag_feature_point(int indx)
          Set the index of the feature point we are dragging based on.
 void set_filter_obj(move_drag_filter fo)
          Set the object which acts as drag filter.
 void set_focus_to(focusable to_obj, event evt, java.lang.Object user_info)
          Override set_focus_to to record the focus object as the filter object.
 void set_focus_to(focusable to_obj, move_drag_filter filt_obj, event evt, java.lang.Object user_info)
          Version of set_focus_to which allows separate move_drag_filter object.
 void set_focus_to(focusable to_obj, move_drag_filter filt_obj, int f_pt, event evt, java.lang.Object user_info)
          Version of set_focus_to which allows separate move_drag_filter object and feature point specification.
 
Methods inherited from class sub_arctic.input.single_focus_agent
add_to_focus, clear_focus, remove_from_focus
 
Methods inherited from class sub_arctic.input.focus_dispatch_agent
focus_item, focus_set_size, is_in_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

drag_start

protected java.lang.reflect.Method drag_start
Hold a reference to the Method for drag_start

drag_feedback

protected java.lang.reflect.Method drag_feedback
Hold a reference to the Method for drag_feedback

drag_end

protected java.lang.reflect.Method drag_end
Hold a reference to the Method for drag_end

_drag_feature_point

protected int _drag_feature_point
Index of the feature point we are dragging based on. The feature point is used to filter the dragging. In particular, the position of the feature point is what is passed to the filter applied to the drag. The result of the filter is used to calculate a top left value which is passed to the drag protocol routines. This position is such that it places the feature point at its filtered position. Standard indexes for the four corners and center are defined in sub_arctic.lib.interactor_consts. A value of FEATURE_NONE (== -1) can be used to denote the "drag point" -- the point within the object that that the initial mouse-down occured at, which would also normally be the position of the cursor.
See Also:
interactor_consts, base_interactor.feature_point(int), base_interactor.drag_feature_point()

_filter_obj

protected move_drag_filter _filter_obj
Object which acts as drag filter. This filter object transforms the drag point (which is the position of the "feature point" within the object -- see drag_feature_point()) into other points and is used to limit the area of the drag or produce other special drag effects. If this is null, no filtering is done.
See Also:
drag_feature_point()

start_x

protected int start_x
Start x position of the current drag (in global coordinates)

start_y

protected int start_y
Start y position of the current drag (in global coordinates)

grab_x

protected int grab_x
Grab x position (start position in local coordinates). This is where the cursor was positioned relative to the object when the mouse button went down to initiate the drag.

grab_y

protected int grab_y
Grab y position (start position in local coordinates). This is where the cursor was positioned relative to the object when the mouse button went down to initiate the drag.
Constructor Detail

move_drag_focus_agent

public move_drag_focus_agent()
Default constructor
Method Detail

allowable_focus

public boolean allowable_focus(focusable candidate_obj)
Method to limit the objects allowable as members of the focus set. In this case we only allow things which implement move_draggable.
Parameters:
candidate_obj - the object we are deciding upon
Returns:
a boolean indicating if the object is acceptable
Overrides:
allowable_focus in class focus_dispatch_agent

event_is_useful

public boolean event_is_useful(event evt)
Method to determine if this agent needs to see a given event. In this case we are interested in MOUSE_DRAGGED, MOUSE_MOVED and MOUSE_RELEASED only.
Parameters:
evt - the event in question
Overrides:
event_is_useful in class dispatch_agent

drag_feature_point

public int drag_feature_point()
Index of the feature point we are dragging based on. The feature point is used to filter the dragging. In particular, the position of the feature point is what is passed to the filter applied to the drag. The result of the filter is used to calculate a top left value which is passed to the drag protocol routines. This position is such that it places the feature point at its filtered position. Standard indexes for the four corners and center are defined in sub_arctic.lib.interactor_consts. A value of FEATURE_NONE (== -1) can be used to denote the "drag point" -- the point within the object that that the initial mouse-down occured at, which would also normally be the position of the cursor.
Returns:
the index of the feature point in use for the current drag

set_drag_feature_point

public void set_drag_feature_point(int indx)
Set the index of the feature point we are dragging based on. The feature point is used to filter the dragging. In particular, the position of the feature point is what is passed to the filter applied to the drag. The result of the filter is used to calculate a top left value which is passed to the drag protocol routines. This position is such that it places the feature point at its filtered position. Standard indexes for the four corners and center are defined in sub_arctic.lib.interactor_consts. A value of FEATURE_NONE (== -1) can be used to denote the "drag point" -- the point within the object that that the initial mouse-down occured at, which would also normally be the position of the cursor.
Parameters:
indx - the new feature point index

filter_obj

public move_drag_filter filter_obj()
Object which acts as drag filter. This filter object transforms the drag point (which is the position of the "feature point" within the object -- see drag_feature_point()) into other points and is used to limit the area of the drag or produce other special drag effects. If this is null, no filtering is done.
Returns:
the current filter object

set_filter_obj

public void set_filter_obj(move_drag_filter fo)
Set the object which acts as drag filter. This filter object transforms the drag point (which is the position of the "feature point" within the object -- see drag_feature_point()) into other points and is used to limit the area of the drag or produce other special drag effects. If this is set to null, no filtering is done.
Parameters:
fo - the new filter object

set_focus_to

public void set_focus_to(focusable to_obj,
                         event evt,
                         java.lang.Object user_info)
Override set_focus_to to record the focus object as the filter object. If the focus object implements move_drag_filter, then we use it as the filter. Otherwise we set the filter to null (which means no filtering). We also record the feature point of the object that is to be used for the drag (as returned by its drag_feature_point() method).
Parameters:
to_obj - the object which is the new drag focus
evt - the event which "caused" the focus to occur
user_info - information that is to be passed to the object whenever input is dispatched to it
Overrides:
set_focus_to in class single_focus_agent

set_focus_to

public void set_focus_to(focusable to_obj,
                         move_drag_filter filt_obj,
                         event evt,
                         java.lang.Object user_info)
Version of set_focus_to which allows separate move_drag_filter object.
Parameters:
to_obj - the object which is the new drag focus
filt_obj - the filter to be applied to the drag
evt - the event which "caused" the focus to occur
user_info - information that is to be passed to the object whenever input is dispatched to it

set_focus_to

public void set_focus_to(focusable to_obj,
                         move_drag_filter filt_obj,
                         int f_pt,
                         event evt,
                         java.lang.Object user_info)
Version of set_focus_to which allows separate move_drag_filter object and feature point specification. If this constructor is used, the drag_feature_point() method of the object is ignored in favor of the point given here.
Parameters:
to_obj - the object which is the new drag focus
filt_obj - the filter to be applied to the drag
f_pt - the index of the feature point to be used for this drag
evt - the event which "caused" the focus to occur
user_info - information that is to be passed to the object whenever input is dispatched to it

filter_drag_pt

protected java.awt.Point filter_drag_pt(interactor for_obj,
                                        java.awt.Point pt)
Filter a drag point. If there were no filtering, then the point given would correspond to the grab point within the object (expressed in the parent coordinate system). Based on this we compute where the object's feature point would be. We filter this point, then calculate the location of the top-left corner of the object that places the feature point at the filtered location. This top-left corner is what is finally returned.
Parameters:
for_obj - The object we are filtering the point for
pt - The actual point being filtered (in parent's coordinates)
Returns:
the filtered point (in parent's coordinates)

inform_focus_enter

protected void inform_focus_enter(focusable obj,
                                  event evt,
                                  java.lang.Object user_info)
Override the normal inform_focus_enter to deliver the drag_start().
Parameters:
obj - the object we are dragging
evt - the event that "caused" the start of drag (typically a mouse button down event)
user_info - an uninterpreted object to be passed to the object
Overrides:
inform_focus_enter in class focus_dispatch_agent

inform_focus_exit

protected void inform_focus_exit(focusable obj,
                                 event evt,
                                 java.lang.Object user_info)
Override the normal inform_focus_exit to deliver the drag_end().
Parameters:
obj - the object we are dragging
evt - the event that "caused" the end of drag (typically a mouse button up event)
user_info - an uninterpreted object to be passed to the object
Overrides:
inform_focus_exit in class focus_dispatch_agent

dispatch_event

public boolean dispatch_event(event evt,
                              java.lang.Object user_info,
                              interactor to_obj,
                              int seq_num)
Dispatch an event under this protocol. This will send either a drag_feedback() or drag_end() to the object.
Parameters:
evt - the event being dispatched (already approved by event_is_useful())
user_info - an uninterpreted info object to be passed to the dragged object
to_obj - for focus agents this is always null
seq_num - for focus agents this is ignored
Returns:
value indicating if the event was consumed
Overrides:
dispatch_event in class focus_dispatch_agent