sub_arctic.input
Interface snap_targetable

All Known Implementing Classes:
point_snap_target
public abstract interface snap_targetable
extends interactor

This interface provides the input protocol for objects which are the targets of snapping. Normally these objects are stationary while snap_draggable objects are dragged. Where the right conditions occur, feedback is produced which snaps the objects together in some way (typically by pulling the dragged object to the target object). Snapping is considered to be "from" snap_draggable objects (called the "drag" objects) "to" snap_targetable objects (called the "target" objects). Both this protocol and the snap_draggable protocol are managed and delivered by the snap_drag_agent.

Snapping requires a two part test. The first part is geometric. In this part we determine if a feature point of the drag object is close enough geometrically to snap to the target. If this test passes, then a second semantic test is performed to determine if the two objects are semantically compatible (this second test by snap_from_ok() may involve type tests and/or exchange of information between the drag and target objects). If both snapping tests succeed, and the snap is the closest candidate snap, the snap will occur.

If their are no suitable snaps, but some snaps pass the geometric test (i.e., are close enough) then "anti-snaps" will be considered. An anti-snap is designed to provide feedback about a negative condition -- it is typically used to produce a kind of dynamic "error message" that indicates why a geometrically possible snap is not semantically suitable. Anti-snaps must pass a second semantic test (performed by anti_snap_from_ok()) before they are activated.

See Also:
snap_draggable, snap_drag_agent

Fields inherited from class sub_arctic.lib.interactor_consts
DAMAGED, ENABLED, ENABLED_HAS_EXT_NOTIFY, ENABLED_IN_PROCESS, ENABLED_IS_HORIZONTAL, ENABLED_OOD, FEATURE_BOTTOM_LEFT, FEATURE_BOTTOM_RIGHT, FEATURE_CENTER, FEATURE_NONE, FEATURE_TOP_LEFT, FEATURE_TOP_RIGHT, FIRST_FREE_FEATURE, FIRST_FREE_FLAG, FIXED_CHILDREN, H, H_HAS_EXT_NOTIFY, H_IN_PROCESS, H_OOD, IS_ENABLED, IS_VISIBLE, OOD_BITS, PART_A, PART_A_HAS_EXT_NOTIFY, PART_A_IN_PROCESS, PART_A_IS_HORIZONTAL, PART_A_OOD, PART_B, PART_B_HAS_EXT_NOTIFY, PART_B_IN_PROCESS, PART_B_IS_HORIZONTAL, PART_B_OOD, STYLE_LOCKED, SUPPORTS_CHILDREN, TRAV_DRAW, TRAV_PICK, TRAV_POST, TRAV_PRE, VISIBLE, VISIBLE_HAS_EXT_NOTIFY, VISIBLE_IN_PROCESS, VISIBLE_IS_HORIZONTAL, VISIBLE_OOD, W, W_HAS_EXT_NOTIFY, W_IN_PROCESS, W_OOD, X, X_HAS_EXT_NOTIFY, X_IN_PROCESS, X_OOD, Y, Y_HAS_EXT_NOTIFY, Y_IN_PROCESS, Y_OOD
 
Fields inherited from class sub_arctic.constraints.std_constraint_consts
FIRST_CHILD, LAST_CHILD, MAX_CHILD, MIN_CHILD, NEXT_SIBLING, NO_CONSTRAINT, OTHER, PARENT, PREV_SIBLING, SELF, ZERO
 
Method Summary
 boolean anti_snap_feedback(event evt, java.awt.Point orig_pt, java.awt.Point snap_pt, snap_draggable drag_obj, int feature_pt_indx, java.lang.Object anti_snap_info, java.lang.Object user_info)
          Perform feedback while an anti-snap is active.
 java.lang.Object anti_snap_from_ok(java.awt.Point pt, snap_draggable drag_obj, int feature_pt_indx)
          Determine if a geometrically accepted snap which has been semantically rejected (by snap_from_obj()) should provide anti-snap feedback.
 boolean anti_snap_from(event evt, java.awt.Point orig_pt, java.awt.Point snap_pt, snap_draggable drag_obj, int feature_pt_indx, java.lang.Object anti_snap_info, java.lang.Object user_info)
          Do anti-snap feedback corresponding to an anti-snap from the given drag object.
 boolean point_snaps(java.awt.Point pt, int_holder return_dist2, java.awt.Point return_snap_pt)
          Determine if the given point (in local coordinates) is close enough to snap to this object (and return the square of its distance, and the point snapped to).
 boolean snap_feedback(event evt, java.awt.Point orig_pt, java.awt.Point snap_pt, snap_draggable drag_obj, int feature_pt_indx, java.lang.Object user_info)
          Perform feedback while a snap is active.
 boolean snap_from_ok(java.awt.Point pt, snap_draggable drag_obj, int feature_pt_indx)
          Determine if a geometrically accepted snap should be semantically accepted.
 boolean snap_from(event evt, java.awt.Point orig_pt, java.awt.Point snap_pt, snap_draggable drag_obj, int feature_pt_indx, java.lang.Object user_info)
          Do the feedback corresponding to a snap from the given drag object.
 boolean unanti_snap_from(event evt, java.awt.Point orig_pt, java.awt.Point snap_pt, snap_draggable drag_obj, int feature_pt_indx, java.lang.Object anti_snap_info, java.lang.Object user_info)
          Remove anti-snap feedback for an anti-snap that is now being broken.
 boolean unsnap_from(event evt, java.awt.Point orig_pt, java.awt.Point snap_pt, snap_draggable drag_obj, int feature_pt_indx, java.lang.Object user_info)
          Remove feedback for a snap that is now being broken.
 
Methods inherited from interface sub_arctic.lib.interactor
active_constraints, add_child, add_user_datum, attach_dependent, bound, child_index, child, configure, constraint_flag_is_set, constraint_on, custom_fun1, custom_fun2, damage_from_child, damage_self, damage_self, damage_self, damage_self, damage_self, detach_dependent, do_action, do_action, drag_feature_point, draw_self, enabled_constraint, enabled, eval_enabled, eval_h, eval_part_a, eval_part_b, eval_visible, eval_w, eval_x, eval_y, eval, feature_point_enabled, feature_point, find_child, fixed_children, flag_is_set, get_awt_component, get_external_constraint, get_part, get_top_level, get_value, global_to_local, global_to_local, h_constraint, h, handle_cycle, inform_ood, insert_child, inside_bounds, into_local, into_local, into_parent, into_parent, intrinsic_constraints, is_constrained, local_to_global, local_to_global, mark_all_ood, mark_enabled_ood, mark_h_ood, mark_ood, mark_part_a_ood, mark_part_b_ood, mark_reparented_ood, mark_visible_ood, mark_w_ood, mark_x_ood, mark_y_ood, marked_ood, move_child_downward, move_child_downward, move_child_to_bottom, move_child_to_bottom, move_child_to_top, move_child_to_top, move_child_upward, move_child_upward, move_downward, move_to_bottom, move_to_top, move_upward, next_sibling, num_actions, num_children, num_feature_points, parent, part_a_constraint, part_a, part_b_constraint, part_b, pick, picked_by, pos, prev_sibling, remove_child, remove_child, remove_user_datum, restyle, set_child_index, set_child, set_constraint, set_constraint, set_enabled_constraint, set_enabled_constraint, set_enabled_constraint, set_enabled, set_h_constraint, set_h_constraint, set_h_constraint, set_h, set_parent, set_part_a_constraint, set_part_a_constraint, set_part_a_constraint, set_part_a, set_part_b_constraint, set_part_b_constraint, set_part_b_constraint, set_part_b, set_pos, set_pos, set_size, set_style_lock, set_user_info, set_visible_constraint, set_visible_constraint, set_visible_constraint, set_visible, set_w_constraint, set_w_constraint, set_w_constraint, set_w, set_x_constraint, set_x_constraint, set_x_constraint, set_x, set_y_constraint, set_y_constraint, set_y_constraint, set_y, size, style_change, supports_children, tag_str, toString, traverse_and_collect, trivial_reject, user_data, user_info, value_ood, visible_constraint, visible, w_constraint, w, x_constraint, x_into_local, x_into_parent, x, y_constraint, y_into_local, y_into_parent, y
 

Method Detail

point_snaps

public boolean point_snaps(java.awt.Point pt,
                           int_holder return_dist2,
                           java.awt.Point return_snap_pt)
Determine if the given point (in local coordinates) is close enough to snap to this object (and return the square of its distance, and the point snapped to). This is a geometric test only. To maintain uniformity, objects should normally report a snap here if the square of the distance to the point is less than or equal to snap_drag_agent.snap_dist2(). The return_dist2 object should be modified so that it contains the square of the distance from the point to the target. The return_snap_pt object should be modified to return the final snap point. Both return_dist2 and return_snap_pt are ignored if the routine returns false.
Parameters:
pt - the point being tested (in local coordinates).
return_dist2 - to be modified to contain the square of the distance to the point (ignored if false is returned).
return_snap_pt - to be modified to contain the final snap target point in local coordinates (ignored if false is returned).
Returns:
boolean indicating whether snap is geometrically accepted.

snap_from_ok

public boolean snap_from_ok(java.awt.Point pt,
                            snap_draggable drag_obj,
                            int feature_pt_indx)
Determine if a geometrically accepted snap should be semantically accepted. Normally target objects only accept snaps from drag objects that meet certain qualifications. This routine is responsible for determining if the given object and the given feature point within that object meets the current criteria for a snap. This normally involves determining whether the drag object implements a certain (application specific) interface, then using the protocol of that interface to query the properties of the drag object.
Parameters:
pt - the pre-snap location of the feature point being tested.
drag_obj - the drag object being tested.
feature_pt_indx - the index of the feature point (within drag_obj) being tested.
Returns:
whether the snap is acceptable.

anti_snap_from_ok

public java.lang.Object anti_snap_from_ok(java.awt.Point pt,
                                          snap_draggable drag_obj,
                                          int feature_pt_indx)
Determine if a geometrically accepted snap which has been semantically rejected (by snap_from_obj()) should provide anti-snap feedback. (Anti-snap feedback supplies a sort of dynamic error message that indicates why a snap is illegal.) This may involve determining whether the drag object implements a certain (application specific) interface, then using the protocol of that interface to query the properties of the drag object. In other cases a generic "wrong type" anti-snap might be performed.

If no anti-snap is to be applied, null is returned. Otherwise an object with information about the reason for the anti-snap is returned. This object will then be passed to various anti-snap calls.

Parameters:
pt - the pre-snap location of the feature point being tested.
drag_obj - the drag object being tested.
feature_pt_indx - the index of the feature point (within drag_obj) being tested.
Returns:
Object null for no anti-snap. If anti-snap feedback is desired a non-null object is returned (which is later passed to various anti-snap routines in the protocol).

snap_from

public boolean snap_from(event evt,
                         java.awt.Point orig_pt,
                         java.awt.Point snap_pt,
                         snap_draggable drag_obj,
                         int feature_pt_indx,
                         java.lang.Object user_info)
Do the feedback corresponding to a snap from the given drag object.
Parameters:
event - evt the event "causing" the snap.
Point - orig_pt where the dragged object would be without the snap.
Point - snap_pt the snap point.
snap_draggable - drag_obj the dragged object we are snapping from.
int - feature_pt_indx the feature point of that object that we are snapping with.
Object - user_info the user info for this input.
Returns:
boolean indicating if the input has been consumed.

snap_feedback

public boolean snap_feedback(event evt,
                             java.awt.Point orig_pt,
                             java.awt.Point snap_pt,
                             snap_draggable drag_obj,
                             int feature_pt_indx,
                             java.lang.Object user_info)
Perform feedback while a snap is active.
Parameters:
event - evt the event "causing" the snap.
Point - orig_pt where the dragged object would be without the snap.
Point - snap_pt the snap point.
snap_draggable - drag_obj the dragged object we are snapping from.
int - feature_pt_indx the feature point of that object that we are snapping with.
Object - user_info the user info for this input.
Returns:
boolean indicating if the input has been consumed.

unsnap_from

public boolean unsnap_from(event evt,
                           java.awt.Point orig_pt,
                           java.awt.Point snap_pt,
                           snap_draggable drag_obj,
                           int feature_pt_indx,
                           java.lang.Object user_info)
Remove feedback for a snap that is now being broken.
Parameters:
event - evt the event "causing" the unsnap.
Point - orig_pt where the dragged object would be without the snap.
Point - snap_pt the snap point.
snap_draggable - drag_obj the dragged object we are unsnapping from.
int - feature_pt_indx the feature point of that object that we are unsnapping with.
Object - user_info the user info for this input.
Returns:
boolean indicating if the input has been consumed.

anti_snap_from

public boolean anti_snap_from(event evt,
                              java.awt.Point orig_pt,
                              java.awt.Point snap_pt,
                              snap_draggable drag_obj,
                              int feature_pt_indx,
                              java.lang.Object anti_snap_info,
                              java.lang.Object user_info)
Do anti-snap feedback corresponding to an anti-snap from the given drag object.
Parameters:
event - evt the event "causing" the anti-snap.
Point - orig_pt where the dragged object would be without the anti-snap.
Point - snap_pt the anti-snap point.
snap_draggable - drag_obj the dragged object we are anti-snapping from.
int - feature_pt_indx the feature point of that object that we are anti-snapping with.
Object - user_info the user info for this input.
Returns:
boolean indicating if the input has been consumed.

anti_snap_feedback

public boolean anti_snap_feedback(event evt,
                                  java.awt.Point orig_pt,
                                  java.awt.Point snap_pt,
                                  snap_draggable drag_obj,
                                  int feature_pt_indx,
                                  java.lang.Object anti_snap_info,
                                  java.lang.Object user_info)
Perform feedback while an anti-snap is active.
Parameters:
event - evt the event "causing" the anti-snap.
Point - orig_pt where the dragged object would be without the anti-snap.
Point - snap_pt the anti-snap point.
snap_draggable - drag_obj the dragged object we are anti-snapping from.
int - feature_pt_indx the feature point of that object that we are anti-snapping with.
Object - user_info the user info for this input.
Returns:
boolean indicating if the input has been consumed.

unanti_snap_from

public boolean unanti_snap_from(event evt,
                                java.awt.Point orig_pt,
                                java.awt.Point snap_pt,
                                snap_draggable drag_obj,
                                int feature_pt_indx,
                                java.lang.Object anti_snap_info,
                                java.lang.Object user_info)
Remove anti-snap feedback for an anti-snap that is now being broken.
Parameters:
event - evt the event "causing" the unanti-snap.
Point - orig_pt where the dragged object would be without the anti-snap.
Point - snap_pt the anti-snap point.
snap_draggable - drag_obj the dragged object we are unanti-snapping from.
int - feature_pt_indx the feature point of that object that we are unanti-snapping with.
Object - user_info the user info for this input.
Returns:
boolean indicating if the input has been consumed.