Interface sub_arctic.lib.interactor

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface sub_arctic.lib.interactor

public interface interactor
extends Object
extends interactor_consts, std_constraint_consts, value_provider, value_consumer

This interface provides the API for all interactive objects that appear on the screen and/or accept input. Currently all interactor objects in the system are implemented by subclasses of the base_interactor class. See that class for addition common methods and for information about defaults.

The API for interactors covers basic capabilities in 10 areas:

geometry management,
coordinate system
transformations,
hierarchy management,
traversal support,
layout,
picking,
object status,
output,
user information, and
debugging support.

See the user's manual for conceptual material related to each area (each of these areas is covered by a sub-section of the user's manual) and see the methods of base_interactor for additional details of each supported routine.

Note: due to limitations on some (most?) platforms that do not allow for protected methods in interfaces, a number of routines here (and in the interactor interface) that should be protected, are currently public. These are marked by comments in the code, and will be reverted to protected as soon as enough platforms allow.

Author:: Scott Hudson

active_constraints(): Indicate which parts (coordinates/sizes/values) of this object are currently constrained.
add_child(interactor): Add a child to the end of the child list.
add_user_datum(Object): Adds a data item to the collection of data items that we are holding for the user of this interactor.
attach_dependent(int, value_consumer, int): Register something as interested in (dependent on) one of the parts (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B) of this object.
bound(): Bounding rectangle of the object (in parent's coordinate system).
child(int): Return the child at the given index int the child list (whose first element is at index 0).
child_index(): Return the child index of this interactor (within its parent).
configure(): Do the constraint evaluation necessary to make sure all visible objects in the subtree rooted at this object have up-to-date bounds (and other information) prior to drawing.
constraint_flag_is_set(int): Determine if a particular bit (or bits) is set in the constraint_flag set for the interactor.
constraint_on(int): Return a constraint object representing the constraint (if any) attached to the specified part (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B).
custom_fun1(int, int): A custom function accessible in the constraint system.
custom_fun2(int, int, int): A custom function accessible in the constraint system.
damage_from_child(interactor, Object, Point, Dimension): Indicate that a change to a child (or grandchild, etc.) affects the given screen region (expressed in the coordinates of this object).
damage_self(): Indicate that the object has been modified in such as way that any or all of its appearance may change and its area of the screen needs to be redrawn.
damage_self(int, int, int, int): Indicate that the object has been modified in such as way that its appearance within the given area of the screen (expressed in local coordinates) might change and needs to be redrawn.
damage_self(interactor, Object, Point, Dimension): Indicate that the object has been modified in such as way that its appearance within the given area of the screen (expressed in local coordinates) might change and needs to be redrawn.
damage_self(Object): Indicate that the object has been modified in such as way that any or all of its appearance may change and its area of the screen needs to be redrawn.
damage_self(Point, Dimension): Indicate that the object has been modified in such as way that its appearance within the given area of the screen (expressed in local coordinates) might change and needs to be redrawn.
detach_dependent(int, value_consumer, int): Remove an (object,part) pair from the dependent (interested in) list associated with a particular part of this object.
drag_feature_point(): Indicate the current "feature point" of an object.
draw_self(drawable): Draw the object's current appearance.
enabled(): Indicate if object is enabled.
enabled_constraint(): Return a constraint object representing the constraint (if any) attached to enabled.
eval(int): Bring the indicated value up to date with respect to any defining constraints.
eval_enabled(): Bring enabled up to date with respect to any defining constraint.
eval_h(): Bring h up to date with respect to any defining constraint.
eval_part_a(): Bring part_a up to date with respect to any defining constraint.
eval_part_b(): Bring part_b up to date with respect to any defining constraint.
eval_visible(): Bring visible up to date with respect to any defining constraint.
eval_w(): Bring w up to date with respect to any defining constraint.
eval_x(): Bring x up to date with respect to any defining constraint.
eval_y(): Bring y up to date with respect to any defining constraint.
feature_point(int): Access to the "feature points" of an object (by index).
feature_point_enabled(int): Indicate whether the indicated "feature point" of an object is considered to be enabled.
find_child(interactor): Find the given child in the child list and return its index.
fixed_children(): Indicate whether this interactor uses a fixed set of children.
flag_is_set(int): Determine if a particular bit (or bits) is set in the flag set for the interactor.
get_awt_component(): Retrieve the AWT component that this sub_arctic object is drawn within.
get_external_constraint(int): Get the external value provider (if any) associated with the given part value (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B).
get_part(int): Get the specified component (X, Y, W, or H) or of object's geometry.
get_top_level(): Retrieve the top_level interactor (if any) that this object is installed (perhaps several levels down) under.
get_value(int): Get an up-to-date copy of a particular part value(X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B).
global_to_local(int, int): Transform a point in global coordinate space (that is the coordinate system of the top_level object which roots the interactor tree this object is in) into the local space of the object.
global_to_local(Point): Transform a point in global coordinate space (that is the coordinate system of the top_level object which roots the interactor tree this object is in) into the local space of the object.
h(): Height of the object.
h_constraint(): Return a constraint object representing the constraint (if any) attached to h.
handle_cycle(int): Handle a cycle detected in constraints on a given part of this object.
inform_ood(int, int, int): Inform the object that the indicated part of a potentially related object is out-of-date (this is called from ood_inform_all()).
insert_child(int, interactor): Insert a child at the given location, moving current children at or after that index further down in the list.
inside_bounds(int, int): Determine if the given point (in the local coordinates of this object) is inside the extent of this object's normal bound.
into_local(int, int): Transform a point from parent's coordinate space to local coordinates of this object.
into_local(Point): Transform a point from parent's coordinate space to local coordinates of this object.
into_parent(int, int): Transform a local point into the parent's coordinate space.
into_parent(Point): Transform a local point into the parent's coordinate space.
intrinsic_constraints(): Indicate which parts (coordinates/sizes/values) of this object are intrinsically constrained by the internals of the object.
is_constrained(int): Indicate whether a specific part is currently constrained.
local_to_global(int, int): Transform a point in the local coordinate space into the global space (that is the coordinate system of the top_level object which roots the interactor tree this object is in).
local_to_global(Point): Transform a point in the local coordinate space into the global space (that is the coordinate system of the top_level object which roots the interactor tree this object is in).
mark_all_ood(): Mark all geometric parts of this object out of date.
mark_enabled_ood(): Mark enabled value and anything that directly or indirectly depends on it as out-of-date.
mark_h_ood(): Mark h value and anything that directly or indirectly depends on it as out-of-date.
mark_ood(int): Mark the given value as out of date.
mark_part_a_ood(): Mark part_a value and anything that directly or indirectly depends on it as out-of-date.
mark_part_b_ood(): Mark part_b value and anything that directly or indirectly depends on it as out-of-date.
mark_reparented_ood(): Mark all our geometric parts out-of-date and tell all potentially dependent objects that all our parts are out-of-date (this gets done when we move around in the hierarchy).
mark_visible_ood(): Mark visible value and anything that directly or indirectly depends on it as out-of-date.
mark_w_ood(): Mark w value and anything that directly or indirectly depends on it as out-of-date.
mark_x_ood(): Mark x value and anything that directly or indirectly depends on it as out-of-date.
mark_y_ood(): Mark y value and anything that directly or indirectly depends on it as out-of-date.
marked_ood(): Indicate which values are currently marked as potentially out of date with respect to their constraints.
move_child_downward(int): Move the child currently at the given index in the child list down one position in drawing order (which is one position earlier in the list).
move_child_downward(interactor): Move the given child down one position in drawing order of the child list (which is earlier in the list).
move_child_to_bottom(int): Move the child currently at the given index in the child list to the bottom in drawing order (which is first in the list).
move_child_to_bottom(interactor): Move the given child to the bottom of the child list in drawing order (which is first in the list).
move_child_to_top(int): Move the child currently at the given index in the child list to the top in drawing order (which is last in the list).
move_child_to_top(interactor): Move the given child to the top of the child list in drawing order (which is last in the list).
move_child_upward(int): Move the child currently at the given index in the child list up one position in drawing order (which is one position further into the list).
move_child_upward(interactor): Move the given child up one position in drawing order of the child list (which is later in the list).
move_downward(): Move this object one position lower in its parent's drawing order (which is one position earlier in its child list).
move_to_bottom(): Move this object to the bottom of its parent's drawing order (first in its child list).
move_to_top(): Move this object to the top of its parent's drawing order (last in its child list).
move_upward(): Move this object one position higher in its parent's drawing order (which is one position further into its child list).
next_sibling(): Return the next sibling of this object (or null if there is none).
num_children(): Indicate the number of children this interactor currently has.
num_feature_points(): The number of "feature points" of an object.
parent(): Return the parent of this interactor.
part_a(): Return the value of part_a.
part_a_constraint(): Return a constraint object representing the constraint (if any) attached to part_a.
part_b(): Return the value of part_b.
part_b_constraint(): Return a constraint object representing the constraint (if any) attached to part_b.
pick(int, int, pick_collector): Determine if this object and/or any of its decedent objects is "picked" by the the given point.
picked_by(int, int): Determine if the given point (in the local coordinates of this object) is inside the extent of the object picking purposes.
pos(): Position of the top-left corner of this object in the parent coordinate system.
prev_sibling(): Return the previous sibling of this object (or null if there is none).
remove_child(int): Remove the child found at the given index and return it.
remove_child(interactor): Remove the given child from the child list.
remove_user_datum(Object): Removes a data item from the collection of data items that we are holding for the user of this interactor.
restyle(style): Force a restyle of the interactor under the given style.
set_child(int, interactor): Set the child at the given index replacing any child that was previously there.
set_child_index(int): Set the child index of this interactor (within its parent).
set_constraint(int, constraint): Establish a constraint on the given value (one of X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B).
set_constraint(int, value_provider, int): Establish an "external" or "heavyweight" constraint on the given value (one of X, Y, W, H, VISIBLE, ENABLED, PART_A, PART_B).
set_enabled(boolean): Set the enabled status of the interactor.
set_enabled_constraint(constraint): Establish a constraint on the enabled value of this object.
set_enabled_constraint(std_ext_constraint): Establish a standard external constraint on the enabled value of this object.
set_enabled_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the enabled value of this object.
set_h(int): Set height of object.
set_h_constraint(constraint): Establish a constraint on the h value of this object.
set_h_constraint(std_ext_constraint): Establish a standard external constraint on the h value of this object.
set_h_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the h value of this object.
set_parent(interactor): Set the parent of this interactor.
set_part_a(int): Set part_a of object.
set_part_a_constraint(constraint): Establish a constraint on the part_a value of this object.
set_part_a_constraint(std_ext_constraint): Establish a standard external constraint on the part_a value of this object.
set_part_a_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the part_a value of this object.
set_part_b(int): Set part_b of object.
set_part_b_constraint(constraint): Establish a constraint on the part_b value of this object.
set_part_b_constraint(std_ext_constraint): Establish a standard external constraint on the part_b value of this object.
set_part_b_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the part_b value of this object.
set_pos(int, int): Set position of this object in parent coordinate system.
set_pos(Point): Set position of this object in parent coordinate system.
set_size(int, int): Set the size of the object.
set_style_lock(boolean): Lock or unlock the style of this interactor.
set_user_info(Object): Set the uninterpreted "user information" that we are holding for the user of this object.
set_visible(boolean): Set the visibility of the interactor.
set_visible_constraint(constraint): Establish a constraint on the visible value of this object.
set_visible_constraint(std_ext_constraint): Establish a standard external constraint on the visible value of this object.
set_visible_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the visible value of this object.
set_w(int): Set width of object.
set_w_constraint(constraint): Establish a constraint on the w value of this object.
set_w_constraint(std_ext_constraint): Establish a standard external constraint on the w value of this object.
set_w_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the w value of this object.
set_x(int): Set x component of position in parent coordinate system.
set_x_constraint(constraint): Establish a constraint on the x value of this object.
set_x_constraint(std_ext_constraint): Establish a standard external constraint on the x value of this object.
set_x_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the x value of this object.
set_y(int): Set y component of position in parent coordinate system.
set_y_constraint(constraint): Establish a constraint on the y value of this object.
set_y_constraint(std_ext_constraint): Establish a standard external constraint on the y value of this object.
set_y_constraint(value_provider, int): Establish an "external" or "heavyweight" constraint on the y value of this object.
size(): Size of the object.
style_change(): Inform the interactor and all of its descendents that the global current style has changed and that they may need to restyle themselves.
supports_children(): Indicate whether this interactor supports children.
tag_str(): Convert to a small tag string which indicates the type of interactor along with a (hopefully unique) integer (its hashCode) that can be used to identify it during debugging.
toString(): Convert to a human readable string.
traverse_and_collect(int, int, interactor_pred, interactor_pred, traversal_xform, Object, pick_collector): Do a traversal of the interactor tree to collect nodes meeting some criteria (or perform actions on qualifying nodes).
trivial_reject(drawable): Do a trivial reject test that indicates whether the bounds of this object are entirely outside the clipping region of the given drawable object.
user_data(): Access to the collection of data items that we are holding for the user of this interactor.
user_info(): Access to uninterpreted "user information" that we are holding for the user of this object.
value_ood(int, value_provider, int): Indicate that a part value (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B) with an external constraint attached should be marked out-of-date because something it depends on (externally) is out-of-date.
visible(): Indicate if the object considers itself visible.
visible_constraint(): Return a constraint object representing the constraint (if any) attached to visible.
w(): Width of the object.
w_constraint(): Return a constraint object representing the constraint (if any) attached to w.
x(): X position of the top-left corner of this object in the parent coordinate system.
x_constraint(): Return a constraint object representing the constraint (if any) attached to x.
x_into_local(int): Transform an x value from parent's coordinate space to local coords.
x_into_parent(int): Transform an x value form local coordinates into the parent's coordinate space.
y(): Y position of the top-left corner of this object in the parent coordinate system.
y_constraint(): Return a constraint object representing the constraint (if any) attached to y.
y_into_local(int): Transform an y value from parent's coordinate space to local coords.
y_into_parent(int): Transform an y value form local coordinates into the parent's coordinate space.

pos

  public abstract Point pos()

Position of the top-left corner of this object in the parent coordinate system. If either coordinate is controlled by a constraint, it will be brought up to date before this value is returned.

Returns:: Point the position of the object.

  public abstract int x()

X position of the top-left corner of this object in the parent coordinate system. If this coordinate is controlled by a constraint, it will be brought up to date before this value is returned.

Returns:: int the x position of the object.

  public abstract int y()

Y position of the top-left corner of this object in the parent coordinate system. If this coordinate is controlled by a constraint, it will be brought up to date before this value is returned.

Returns:: int the y position of the object.

size

  public abstract Dimension size()

Size of the object. If either the width or height of the object is controlled by a constraint, it will be brought up to date before this value is returned.

Returns:: Dimension the size of the object.

  public abstract int w()

Width of the object. If this value is controlled by a constraint, it will be brought up to date before being returned.

Returns:: int the width of the object.

  public abstract int h()

Height of the object. If this value is controlled by a constraint, it will be brought up to date before being returned.

Returns:: int the height of the object.

bound

  public abstract Rectangle bound()

Bounding rectangle of the object (in parent's coordinate system).

Returns:: Rectangle the bounding rectangle of the object.

visible

  public abstract boolean visible()

Indicate if the object considers itself visible. If a constraint is attached the value will be brought up-to-date with respect to the constraint first.

Returns:: boolean the visibility status of the object

enabled

  public abstract boolean enabled()

Indicate if object is enabled. If a constraint is attached the value will be brought up-to-date with respect to the constraint first.

Note: currently setting an object disabled will keep it from being picked by the normal picking mechanism. This will (normally) disable positional inputs and as a side effect most focus based input (unless the the object is already the focus). However, since enabled status was added after many of the core interactor classes were created, for the most part the interactors in the library do not yet properly reflect the enable/disable status in their visual appearance. This is an important deficiency which we hope to correct in future releases.

Returns:: boolean the enable status of the interactor.

part_a

  public abstract int part_a()

Return the value of part_a. Part_a is a generic value that may be maintained by an interactor to represent some specific semantically meaningful part of its state that it wants to make available for use in the (lightweight) constraint system. For example, sliders make their "thumb value" available as part_a. Here in the base class, part_a is not implemented (it is intrinsically constrained to 0).

Returns:: int the value of part_a (after constraint evaluation if necessary).
See Also:: interactor_with_parts, parent_with_parts

part_b

  public abstract int part_b()

Return the value of part_b. Part_b is a generic value that may be maintained by an interactor to represent some specific semantically meaningful part of its state that it wants to make available for use in the (lightweight) constraint system. For example, sliders make their "thumb value" available as part_b. Here in the base class, part_b is not implemented (it is intrinsically constrained to 0).

Returns:: int the value of part_b (after constraint evaluation if necessary).
See Also:: interactor_with_parts, parent_with_parts

get_part

  public abstract int get_part(int what_code)

Get the specified component (X, Y, W, or H) or of object's geometry. This also now works for VISIBLE, ENABLED, PART_A, and PART_B.

Parameters:: what_code - part number whose value is being requested.
Returns:: int the value of the requested part (after brining any attached constraints up-to-date).

set_pos

  public abstract void set_pos(int xv,
                               int yv)

Set position of this object in parent coordinate system.

Parameters:: int - yv y coordinate of the position.; int - xv x coordinate of the position.

set_pos

  public abstract void set_pos(Point p)

Set position of this object in parent coordinate system.

Parameters:: Point - p the new position.

set_x

  public abstract void set_x(int v)

Set x component of position in parent coordinate system.

Parameters:: int - v the new value for x.

set_y

  public abstract void set_y(int v)

Set y component of position in parent coordinate system.

Parameters:: int - v the new value for y.

set_size

  public abstract void set_size(int wv,
                                int hv)

Set the size of the object.

Parameters:: int - wv the new value for w.; int - hv the new value for h.

set_w

  public abstract void set_w(int v)

Set width of object.

Parameters:: int - v the new value for y.

set_h

  public abstract void set_h(int v)

Set height of object.

Parameters:: int - v the new value for the height.

set_visible

  public abstract void set_visible(boolean v)

Set the visibility of the interactor.

Parameters:: boolean - v the new visibility status.

set_enabled

  public abstract void set_enabled(boolean v)

Set the enabled status of the interactor.

Parameters:: boolean - v new value of enabled.

set_part_a

  public abstract void set_part_a(int v)

Set part_a of object. If part is controlled by a constraint, an exception is thrown.

Parameters:: int - v the new value for part_a

set_part_b

  public abstract void set_part_b(int v)

Set part_b of object. If part is controlled by a constraint, an exception is thrown.

Parameters:: int - v the new value for part_b

local_to_global

  public abstract Point local_to_global(int xv,
                                        int yv)

Transform a point in the local coordinate space into the global space (that is the coordinate system of the top_level object which roots the interactor tree this object is in).

Parameters:: int - xv x coordinate of point to transform.; int - yv y coordinate of point to transform.
Returns:: Point resulting point.

local_to_global

  public abstract Point local_to_global(Point local_pt)

Transform a point in the local coordinate space into the global space (that is the coordinate system of the top_level object which roots the interactor tree this object is in).

Parameters:: Point - local_pt point to transform.
Returns:: Point resulting point.

global_to_local

  public abstract Point global_to_local(int xv,
                                        int yv)

Transform a point in global coordinate space (that is the coordinate system of the top_level object which roots the interactor tree this object is in) into the local space of the object.

Parameters:: int - xv x coordinate of point to transform.; int - yv y coordinate of point to transform.
Returns:: Point resulting point.

global_to_local

  public abstract Point global_to_local(Point global_pt)

Transform a point in global coordinate space (that is the coordinate system of the top_level object which roots the interactor tree this object is in) into the local space of the object.

Parameters:: Point - global_pt point to transform.
Returns:: Point resulting point.

into_local

  public abstract Point into_local(int xv,
                                   int yv)

Transform a point from parent's coordinate space to local coordinates of this object.

Parameters:: int - xv x coordinate of point to transform.; int - yv y coordinate of point to transform.
Returns:: Point resulting point.

into_local

  public abstract Point into_local(Point parent_pt)

Transform a point from parent's coordinate space to local coordinates of this object.

Parameters:: Point - parent_pt point to transform.
Returns:: Point resulting point.

x_into_local

  public abstract int x_into_local(int xv)

Transform an x value from parent's coordinate space to local coords.

Parameters:: int - xv x coordinate of to transform.
Returns:: int resulting x coordinate.

y_into_local

  public abstract int y_into_local(int yv)

Transform an y value from parent's coordinate space to local coords.

Parameters:: int - yv y coordinate of to transform.
Returns:: int resulting y coordinate.

into_parent

  public abstract Point into_parent(Point local_pt)

Transform a local point into the parent's coordinate space.

Parameters:: Point - local_pt point to transform.
Returns:: Point resulting point.

into_parent

  public abstract Point into_parent(int xv,
                                    int yv)

Transform a local point into the parent's coordinate space.

Parameters:: int - xv x coordinate of point to transform.; int - yv y coordinate of point to transform.
Returns:: Point resulting point.

x_into_parent

  public abstract int x_into_parent(int xv)

Transform an x value form local coordinates into the parent's coordinate space.

Parameters:: int - xv x coordinate of to transform.
Returns:: int resulting x coordinate.

y_into_parent

  public abstract int y_into_parent(int yv)

Transform an y value form local coordinates into the parent's coordinate space.

Parameters:: int - yv y coordinate of to transform.
Returns:: int resulting y coordinate.

parent

  public abstract interactor parent()

Return the parent of this interactor.

Returns:: interactor the parent of this interactor or null if this object is an orphan or is a top_level (root) interactor.

set_parent

  public abstract void set_parent(interactor par)

Set the parent of this interactor.

Warning: this method should be protected (but isn't since various implementations don't allow protected in interfaces). This method should not be invoked from "outside the system". Always use the normal child manipulation routines instead.

Parameters:: interactor - par new parent for this object.

get_top_level

  public abstract top_level get_top_level()

Retrieve the top_level interactor (if any) that this object is installed (perhaps several levels down) under. This top_level interactor provides the "global" coordinate space for this interactor. Null is returned if this object is not currently installed somewhere under a top_level interactor.

Returns:: top_level the top_level object we are installed under or null if there is no such object.

get_awt_component

  public abstract Component get_awt_component()

Retrieve the AWT component that this sub_arctic object is drawn within. If this object is not part of an active interface, null will be returned.

child_index

  public abstract int child_index()

Return the child index of this interactor (within its parent). This value is obviously not going to be correct for orphan objects.

Returns:: int index of this interactor within its parent's child list.

set_child_index

  public abstract void set_child_index(int indx)

Set the child index of this interactor (within its parent).

Warning: this method should be protected (but isn't since various implementations don't allow protected in interfaces). This method should not be invoked except from the within the normal child manipulation routines.Always use those routines instead.

Parameters:: int - indx the new index of the child.

prev_sibling

  public abstract interactor prev_sibling()

Return the previous sibling of this object (or null if there is none).

Returns:: interactor the child before this one in its parent's child list or null if there is no such object.

next_sibling

  public abstract interactor next_sibling()

Return the next sibling of this object (or null if there is none).

Returns:: interactor the child after this one in its parent's child list or null if there is no such object.

supports_children

  public abstract boolean supports_children()

Indicate whether this interactor supports children. Interactors that support children will have their SUPPORTS_CHILDREN flag set.

Returns:: boolean indicating whether this object supports children.

fixed_children

  public abstract boolean fixed_children()

Indicate whether this interactor uses a fixed set of children. This is done if the interactor assigns fixed roles/meanings to particular children, or for some other reason limits its total number of children. If this is not set, then the child list is expandable and the system will move entries over to fill in null children (although you cannot rely on this behavior since it is possible to explicitly set a child at a given index to null and sneak nulls into the child list in other ways). If this is set, then removed children will be set to null, and the child list will not be otherwise modified. In addition, if this is set, then operations that would normally reorder children throw an exception instead. An object which uses fixed children will have its FIXED_CHILDREN flag set.

Returns:: boolean indicating whether this object supports fixed children.

num_children

  public abstract int num_children()

Indicate the number of children this interactor currently has. For interactors with fixed children, the interactor will always have this this number, hence it is also the maximum number of children. Interactors that do not support children always return 0. Note: there may be null children in the child list but they are counted as children here.

Returns:: int number of slots in this object's child list.

child

  public abstract interactor child(int i)

Return the child at the given index int the child list (whose first element is at index 0). If the index given is beyond the range of the current child list, or the interactor does not support children, then null is returned. Requests for negative children cause an exception. Note that child lists may contain null children.

Parameters:: int - i the index of the requested child.
Returns:: interactor the child object at the requested index.

set_child

  public abstract void set_child(int at_indx,
                                 interactor chld)

Set the child at the given index replacing any child that was previously there. The child list will be expanded as necessary to accommodate the given child. If the child list is expanded, missing children will be set to null.

Parameters:: int - at_indx position in the child list to replace.; interactor - chld the child object to place at that position.

add_child

  public abstract void add_child(interactor chld)

Add a child to the end of the child list.

Parameters:: interactor - chld the child to add.

insert_child

  public abstract void insert_child(int at_indx,
                                    interactor chld)

Insert a child at the given location, moving current children at or after that index further down in the list.

remove_child

  public abstract interactor remove_child(int at_indx)

Remove the child found at the given index and return it. For interactors with fixed children, the child slot at the index is set to null. For other interactors, later children are moved over in the list to fill in the gap.

Parameters:: int - at_indx the index to remove the child from.

remove_child

  public abstract void remove_child(interactor the_child)

Remove the given child from the child list. For interactors with fixed children, the child slot is set to null. For other interactors, later children are moved up in the list to fill in the gap. If the child is not in the child list, nothing happens.

Parameters:: interactor - the_child the child to be removed.

find_child

  public abstract int find_child(interactor the_child)

Find the given child in the child list and return its index. If the child is no in the child list -1 is returned.

Parameters:: interactor - the_child the child we are searching for.
Returns:: int the index of that child in the child list or -1 if the child is not found.

move_child_to_top

  public abstract void move_child_to_top(int chld_indx)

Move the child currently at the given index in the child list to the top in drawing order (which is last in the list).

Parameters:: int - chld_indx the index of the child to move.

move_child_to_top

  public abstract void move_child_to_top(interactor the_child)

Move the given child to the top of the child list in drawing order (which is last in the list). If the child is not in the list, nothing happens.

Parameters:: interactor - the_child the child to move.

move_child_to_bottom

  public abstract void move_child_to_bottom(int chld_indx)

Move the child currently at the given index in the child list to the bottom in drawing order (which is first in the list).

Parameters:: int - chld_indx the index of the child to move.

move_child_to_bottom

  public abstract void move_child_to_bottom(interactor the_child)

Move the given child to the bottom of the child list in drawing order (which is first in the list). If the child is not in the list, nothing happens.

Parameters:: interactor - the_child the child to move.

move_child_upward

  public abstract void move_child_upward(int chld_indx)

Move the child currently at the given index in the child list up one position in drawing order (which is one position further into the list).

Parameters:: int - chld_indx the index of the child to move.

move_child_upward

  public abstract void move_child_upward(interactor the_child)

Move the given child up one position in drawing order of the child list (which is later in the list). If the child is not in the list, nothing happens.

Parameters:: interactor - the_child the child to move.

move_child_downward

  public abstract void move_child_downward(int chld_indx)

Move the child currently at the given index in the child list down one position in drawing order (which is one position earlier in the list).

Parameters:: int - chld_indx the index of the child to move.

move_child_downward

  public abstract void move_child_downward(interactor the_child)

Move the given child down one position in drawing order of the child list (which is earlier in the list). If the child is not in the list, nothing happens.

Parameters:: interactor - the_child the child to move.

move_to_top

  public abstract void move_to_top()

Move this object to the top of its parent's drawing order (last in its child list).

move_to_bottom

  public abstract void move_to_bottom()

Move this object to the bottom of its parent's drawing order (first in its child list).

move_upward

  public abstract void move_upward()

Move this object one position higher in its parent's drawing order (which is one position further into its child list).

move_downward

  public abstract void move_downward()

Move this object one position lower in its parent's drawing order (which is one position earlier in its child list).

intrinsic_constraints

  public abstract int intrinsic_constraints()

Indicate which parts (coordinates/sizes/values) of this object are intrinsically constrained by the internals of the object. For, example an icon object with a fixed size image would intrinsically constrain its width and height. The result is reported as an integer formed from or-ing together zero or more of the constants: X, Y, W, H, VISIBLE, ENABLED, PART_A or PART_B (for the icon described above that would be W | H).

Returns:: int bitset indicating which parts of the object are intrinsically constrained.

active_constraints

  public abstract int active_constraints()

Indicate which parts (coordinates/sizes/values) of this object are currently constrained. This always includes the intrinsic constraints, but may also indicate other constraints that have been applied to the object. The result is reported as an integer formed from or-ing together zero or more of the constants: X, Y, W, H, VISIBLE, ENABLED, PART_A and PART_B. Values that are constrained may not be assigned to directly (an exception will be thrown).

Parameters:: int - bitset indicating which parts of the object are constrained.

is_constrained

  public abstract boolean is_constrained(int coord_code)

Indicate whether a specific part is currently constrained. The query argument should be one of the constants: X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B. Values that are constrained may not be assigned to (an exception will be thrown).

Parameters:: int - coord_code the object part we are enquiring about.
Returns:: boolean indicating whether it is constrained.

constraint_on

  public abstract constraint constraint_on(int coord_code)

Return a constraint object representing the constraint (if any) attached to the specified part (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B).

Parameters:: int - coord_code the code for the object part in question.
Returns:: constraint the constraint attached to the given part.

x_constraint

  public abstract constraint x_constraint()

Return a constraint object representing the constraint (if any) attached to x.

Returns:: constraint the constraint attached to x.

y_constraint

  public abstract constraint y_constraint()

Return a constraint object representing the constraint (if any) attached to y.

Returns:: constraint the constraint attached to x.

w_constraint

  public abstract constraint w_constraint()

Return a constraint object representing the constraint (if any) attached to w.

Returns:: constraint the constraint attached to w.

h_constraint

  public abstract constraint h_constraint()

Return a constraint object representing the constraint (if any) attached to h.

Returns:: constraint the constraint attached to h.

visible_constraint

  public abstract constraint visible_constraint()

Return a constraint object representing the constraint (if any) attached to visible.

Returns:: constraint the constraint attached to visible.

enabled_constraint

  public abstract constraint enabled_constraint()

Return a constraint object representing the constraint (if any) attached to enabled.

Returns:: constraint the constraint attached to enabled.

part_a_constraint

  public abstract constraint part_a_constraint()

Return a constraint object representing the constraint (if any) attached to part_a.

Returns:: constraint the constraint attached to part_a.

part_b_constraint

  public abstract constraint part_b_constraint()

Return a constraint object representing the constraint (if any) attached to part_b.

Returns:: constraint the constraint attached to part_a.

set_constraint

  public abstract void set_constraint(int coord_code,
                                      constraint a_constraint)

Establish a constraint on the given value (one of X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B). This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: int - coord_code code for the part whose constraint we replace.; constraint - a_constraint the constraint to replace it with.

set_constraint

  public abstract void set_constraint(int code,
                                      value_provider ext_obj,
                                      int ext_part)

Establish an "external" or "heavyweight" constraint on the given value (one of X, Y, W, H, VISIBLE, ENABLED, PART_A, PART_B). This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: int - coord_code code for the part whose constraint we replace.; constraint - a_constraint the constraint to replace it with.

set_x_constraint

  public abstract void set_x_constraint(constraint a_constraint)

Establish a constraint on the x value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception. Only horizontally oriented constraints can be attached to x (if a vertically oriented value is need, use an external constraint).

Parameters:: constraint - a_constraint the constraint to replace it with.

set_x_constraint

  public abstract void set_x_constraint(value_provider ext_obj,
                                        int ext_part)

Establish an "external" or "heavyweight" constraint on the x value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_x_constraint

  public abstract void set_x_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the x value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_y_constraint

  public abstract void set_y_constraint(constraint a_constraint)

Establish a constraint on the y value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception. Only vertically oriented constraints can be attached to y (if a horizontally oriented value is need, use an external constraint).

Parameters:: constraint - a_constraint the constraint to replace it with.

set_y_constraint

  public abstract void set_y_constraint(value_provider ext_obj,
                                        int ext_part)

Establish an "external" or "heavyweight" constraint on the y value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_y_constraint

  public abstract void set_y_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the y value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_w_constraint

  public abstract void set_w_constraint(constraint a_constraint)

Establish a constraint on the w value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception. Only horizontally oriented constraints can be attached to w (if a vertically oriented value is need, use an external constraint).

Parameters:: constraint - a_constraint the constraint to replace it with.

set_w_constraint

  public abstract void set_w_constraint(value_provider ext_obj,
                                        int ext_part)

Establish an "external" or "heavyweight" constraint on the w value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_w_constraint

  public abstract void set_w_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the w value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_h_constraint

  public abstract void set_h_constraint(constraint a_constraint)

Establish a constraint on the h value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception. Only vertically oriented constraints can be attached to h (if a horizontally oriented value is need, use an external constraint).

Parameters:: constraint - a_constraint the constraint to replace it with.

set_h_constraint

  public abstract void set_h_constraint(value_provider ext_obj,
                                        int ext_part)

Establish an "external" or "heavyweight" constraint on the h value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_h_constraint

  public abstract void set_h_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the h value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_visible_constraint

  public abstract void set_visible_constraint(constraint a_constraint)

Establish a constraint on the visible value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: constraint - a_constraint the constraint to replace it with.

set_visible_constraint

  public abstract void set_visible_constraint(value_provider ext_obj,
                                              int ext_part)

Establish an "external" or "heavyweight" constraint on the visible value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_visible_constraint

  public abstract void set_visible_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the visible value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_enabled_constraint

  public abstract void set_enabled_constraint(constraint a_constraint)

Establish a constraint on the enabled value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: constraint - a_constraint the constraint to replace it with.

set_enabled_constraint

  public abstract void set_enabled_constraint(value_provider ext_obj,
                                              int ext_part)

Establish an "external" or "heavyweight" constraint on the enabled value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_enabled_constraint

  public abstract void set_enabled_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the enabled value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_part_a_constraint

  public abstract void set_part_a_constraint(constraint a_constraint)

Establish a constraint on the part_a value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: constraint - a_constraint the constraint to replace it with.

set_part_a_constraint

  public abstract void set_part_a_constraint(value_provider ext_obj,
                                             int ext_part)

Establish an "external" or "heavyweight" constraint on the part_a value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_part_a_constraint

  public abstract void set_part_a_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the part_a value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

set_part_b_constraint

  public abstract void set_part_b_constraint(constraint a_constraint)

Establish a constraint on the part_b value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: constraint - a_constraint the constraint to replace it with.

set_part_b_constraint

  public abstract void set_part_b_constraint(value_provider ext_obj,
                                             int ext_part)

Establish an "external" or "heavyweight" constraint on the part_b value of this object. This attaches a value exported by a particular part of some value_provider object and replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: value_provider - ext_obj the external object providing the value.; int - ext_part the part number of the part of that object providing the value.

set_part_b_constraint

  public abstract void set_part_b_constraint(std_ext_constraint ext_cnstr)

Establish a standard external constraint on the part_b value of this object. This replaces any constraint currently in place. However, an attempt to replace an intrinsic constraint will result in an exception.

Parameters:: std_ext_constraint - ext_cnstr the constraint to attach.

marked_ood

  public abstract int marked_ood()

Indicate which values are currently marked as potentially out of date with respect to their constraints. Typically this information is needed only by the constraint system, since values are generally brought up to date whenever they are requested.

Returns:: s int a bitset indicating the parts of this object which are currently marked out-of-date.

mark_ood

  public abstract void mark_ood(int coord_code)

Mark the given value as out of date. This will recursively mark anything that directly or indirectly depends on the given value. This should normally only be called by the constraint system, since setting values via set_*() will automatically call this routine.

Parameters:: int - the part to mark out-of-date. This should be one of the values: X, Y, W, H, ENABLED, PART_A, or PART_B.

mark_all_ood

  public abstract void mark_all_ood()

Mark all geometric parts of this object out of date. This happens for example when we reparent it.

mark_x_ood

  public abstract void mark_x_ood()

Mark x value and anything that directly or indirectly depends on it as out-of-date.

mark_y_ood

  public abstract void mark_y_ood()

Mark y value and anything that directly or indirectly depends on it as out-of-date.

mark_w_ood

  public abstract void mark_w_ood()

Mark w value and anything that directly or indirectly depends on it as out-of-date.

mark_h_ood

  public abstract void mark_h_ood()

Mark h value and anything that directly or indirectly depends on it as out-of-date.

mark_visible_ood

  public abstract void mark_visible_ood()

Mark visible value and anything that directly or indirectly depends on it as out-of-date.

mark_enabled_ood

  public abstract void mark_enabled_ood()

Mark enabled value and anything that directly or indirectly depends on it as out-of-date.

mark_part_a_ood

  public abstract void mark_part_a_ood()

Mark part_a value and anything that directly or indirectly depends on it as out-of-date.

mark_part_b_ood

  public abstract void mark_part_b_ood()

Mark part_b value and anything that directly or indirectly depends on it as out-of-date.

mark_reparented_ood

  public abstract void mark_reparented_ood()

Mark all our geometric parts out-of-date and tell all potentially dependent objects that all our parts are out-of-date (this gets done when we move around in the hierarchy). This affects, x, y, w, and h, but not visible, enabled, part_a, or part_b.

inform_ood

  public abstract void inform_ood(int from_obj_type,
                                  int from_part,
                                  int nth_child)

Inform the object that the indicated part of a potentially related object is out-of-date (this is called from ood_inform_all()). The related object can be one of OBJCODE_SELF, OBJCODE_PARENT, OBJCODE_SOME_CHILD, OBJCODE_NEXT_SIBLING, or OBJCODE_PREV_SIBLING, and the indicated part can be X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B.

The nth_child parameter is used only if OBJCODE_SOME_CHILD is passed, in which case it indicates the index of the child in question. If parts of this object are actually dependent upon the given part they are marked out-of-date and the mark out-of-date traversal is continued recursively from them. If not, we do nothing.

Parameters:: int - from_type the type of object we are being informed by (must be one of OBJCODE_SELF, OBJCODE_PARENT, OBJCODE_SOME_CHILD, OBJCODE_NEXT_SIBLING, or OBJCODE_PREV_SIBLING).; int - from_part the part code of the part of that object which is informing us that it is out-of-date.; int - nth_child if from_type is OBJCODE_SOME_CHILD, this parameter indicates which child it is (otherwise it is ignored).

handle_cycle

  public abstract boolean handle_cycle(int part_code)

Handle a cycle detected in constraints on a given part of this object. If this routine returns true, then evaluation proceeds. If this returns false then, the current value of the attribute (which may have been set by this routine) is left in place but marked up-to-date.

Parameters:: int - part_code the part of this object that involves a cycle.
Returns:: boolean indicating whether we should proceed with evaluation.
See Also:: handle_cycle

eval

  public abstract void eval(int coord_code)

Bring the indicated value up to date with respect to any defining constraints. This routine does not typically need to be called explicitly since normal requests for values do evaluations before returning.

Parameters:: int - coord_code the part whose value should be evaluated.

eval_x

  public abstract void eval_x()

Bring x up to date with respect to any defining constraint.

eval_y

  public abstract void eval_y()

Bring y up to date with respect to any defining constraint.

eval_w

  public abstract void eval_w()

Bring w up to date with respect to any defining constraint.

eval_h

  public abstract void eval_h()

Bring h up to date with respect to any defining constraint.

eval_visible

  public abstract void eval_visible()

Bring visible up to date with respect to any defining constraint.

eval_enabled

  public abstract void eval_enabled()

Bring enabled up to date with respect to any defining constraint.

eval_part_a

  public abstract void eval_part_a()

Bring part_a up to date with respect to any defining constraint.

eval_part_b

  public abstract void eval_part_b()

Bring part_b up to date with respect to any defining constraint.

get_external_constraint

  public abstract provider_part_ref get_external_constraint(int for_part)

Get the external value provider (if any) associated with the given part value (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B). Returns null if there is no external provider.

Parameters:: int - for_part the part we are asking about.
Returns:: provider_part_ref the external value provider associated with that part, or null if there is none.

get_value

  public abstract Object get_value(int part_number)

Get an up-to-date copy of a particular part value(X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B). An Integer object will be returned.

Parameters:: int - part_number the part being requested.
Returns:: Object an Integer object containing the value of the requested part.

custom_fun1

  public abstract int custom_fun1(int val1,
                                  int const_val)

A custom function accessible in the constraint system. This function is accessible from the (lightweight) constraint system and can be overridden by particular subclasses to perform custom computations associated with that class. This version is passed a single parameter value derived from a depended upon object, plus a constant value taken from the constraint.

Important note: for the constraint system to work correctly, this function must compute its value solely on its parameters and not access additional information from this object or other objects (since the attribute constrained to the result of this function will not hear about changes and be properly updated).

Parameters:: int - val1 a value from a depended upon object.; int - const_val a constant value taken from the constraint.
Returns:: s int the result of evaluating of the function.

custom_fun2

  public abstract int custom_fun2(int val1,
                                  int val2,
                                  int const_val)

A custom function accessible in the constraint system. This function is accessible from the (lightweight) constraint system and can be overridden by particular subclasses to perform custom computations associated with that class. This version is passed two parameter values derived from a depended upon object, plus a constant value taken from the constraint.

Parameters:: int - val1 a value from a depended upon object.; int - val2 another value from a depended upon object.; int - const_val a constant value taken from the constraint.
Returns:: s int the result of evaluating the function.

attach_dependent

  public abstract void attach_dependent(int on_part_num,
                                        value_consumer dep_obj,
                                        int dep_part)

Register something as interested in (dependent on) one of the parts (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B) of this object. The entity registered is a part within a value_consumer object (typically an external_constraint). Whenever the part value in question is marked out-of-date, the value_ood() method is invoked on each currently registered (object,part) pair.

Parameters:: int - on_part_num the part of this object that the dependency is being attached to.; value_consumer - dep_obj the object that is dependent.; int - dep_part the part within that object which is dependent.

detach_dependent

  public abstract void detach_dependent(int on_part_num,
                                        value_consumer dep_obj,
                                        int dep_part)

Remove an (object,part) pair from the dependent (interested in) list associated with a particular part of this object.

Parameters:: int - on_part_num the part of this object that the dependency is attached to.; value_consumer - dep_obj the object that was dependent.; int - dep_part the part within that object which was dependent.

value_ood

  public abstract void value_ood(int for_part_here,
                                 value_provider prov_obj,
                                 int prov_part)

Indicate that a part value (X, Y, W, H, VISIBLE, ENABLED, PART_A, or PART_B) with an external constraint attached should be marked out-of-date because something it depends on (externally) is out-of-date.

Parameters:: int - for_part_here part within this object that should be marked out-of-date.; value_provider - prov_obj object that we depend on.; int - prov_part part within that object that is

configure

  public abstract void configure()

Do the constraint evaluation necessary to make sure all visible objects in the subtree rooted at this object have up-to-date bounds (and other information) prior to drawing. This routine implements the "configure" pass which occurs right before the pass that does the actual drawing.

Important note: In addition to the work done in the base_interactor class (which should almost always be done by invoking super() from any subclass implementations), each subclass should also be certain to update anything which could effect its bounds here, and not in draw_self_local(). So for example if the height of an object depends on a font that might have changed, the potentially new height must be computed and set here and not in draw_self_local(). In general, for things to work out right it must be the case that this object's bound is correct once this method returns. The reason for this is that by the time draw_self_local() is called, the clipping region corresponding to the bound of this object will have already been set and changing the bound then will not modify the clipping region accordingly (so the drawing may be incorrect).

inside_bounds

  public abstract boolean inside_bounds(int pt_x,
                                        int pt_y)

Determine if the given point (in the local coordinates of this object) is inside the extent of this object's normal bound. You should not normally override this routine to handle picking of non-rectangular objects. Do that in picked_by() instead.

Parameters:: int - pt_x x coordinate of the query point.; int - pt_y y coordinate of the query point.
Returns:: boolean indicating whether the point is inside the objects bounding box.
See Also:: picked_by

picked_by

  public abstract boolean picked_by(int pt_x,
                                    int pt_y)

Determine if the given point (in the local coordinates of this object) is inside the extent of the object picking purposes. Be default, this method just checks the normal bound (bounding box), however, it can be overridden to support accurate picking of non-rectangular objects.

Parameters:: int - pt_x x coordinate of the query point.; int - pt_y y coordinate of the query point.
Returns:: boolean indicating whether the point is inside the objects bounding box.
See Also:: inside_bounds

pick

  public abstract void pick(int pt_x,
                            int pt_y,
                            pick_collector pick_list)

Determine if this object and/or any of its decedent objects is "picked" by the the given point. If it is, it must add itself to the end of the given given pick_collection by calling report_pick(). If not, it should leave the pick_collector as is.

This method is also responsible for recursively invoking itself as appropriate for its children (this is usually done using the base_interactor.pick_within_children() utility routine). By default we pick against any children first (since they are by default drawn last) and then this object. However, if the drawing order is changed from the default, this method must be changed to reflect (the reverse of) that non-standard order. For example, if this object does drawing both under and on top of its children, two sets of part specific tests would typically be needed, one before recursively picking the children, and one after.

Parameters:: int - pt_x x coordinate of the query point.; int - pt_y y coordinate of the query point.; pick_collector - pick_list object that collects and returns pick results.
See Also:: pick_within_children

traverse_and_collect

  public abstract void traverse_and_collect(int traversal_kind,
                                            int traversal_order,
                                            interactor_pred inclusion_test,
                                            interactor_pred continue_test,
                                            traversal_xform xform_parent_to_child,
                                            Object parameters,
                                            pick_collector collection_result)

Do a traversal of the interactor tree to collect nodes meeting some criteria (or perform actions on qualifying nodes). Traversals are given a specialized "kind" so that subclasses can recognize and override behavior for certain traversals, while keeping default behavior for the rest. In addition, several traversal orders are provided. Qualification for collection (or action) is done by an inclusion test predicate object. This predicate is given the interactor in question as well as some (optional) data specific to the predicate. This data is passed in from the root of the traversal and (optionally) transformed from parent to child values as the traversal proceeds. Objects are collected (along with optional additional data) by adding them to a pick_collector object. Recursive traversal is stopped when either leaves are reached or the continue_test predicate for an interior node fails (in which case its children will not be visited).

Examples of possible traversals include:
Replacement for the normal pick operation:

   traverse_and_collect(pick_trav, TRAV_DRAW, pt_inside_bounds, pt_inside_bounds,
                        coord_parent_to_local, pick_pt, result);

and a tree dump:

   traverse_and_collect(dump_trav, TRAV_PRE, dump_interactor, incr_int,
                        null, new Integer(0), result)

where dump_interactor printed to the node to System.out at the indentation level of its Integer parameter, but always returns false

Parameters:: traversal_kind - a unique integer (i.e., generated by manager.unique_int()) that represents the kind of traversal being performed.; traversal_order - one of TRAV_DRAW, TRAV_PICK, TRAV_PRE, or TRAV_POST indicating drawing order, pick order, left-to-right pre-order, or left-to-right post-order traversal.; inclusion_test - an interactor predicate object which is to perform the inclusion test for this traversal. If the traversal is being done for its action side-effects (rather than a collection, per se) then this object's test() method should perform that action on selected nodes. A null inclusion_test is treated as a function that selects everything (always returns true).; continue_test - an interactor_predicate object which determines if the given object's children are traversed. If this method returns false, then the children will not be visited. A null continue_test is is treated as a function that always returns true.; xform_parent_to_child - object containing a method to transform the parameters data (passed to the inclusion_test) from its parent condition to the condition suitable for use by a given child. This can be used, for example, to transform a point from the parent's coordinates into those of a child. A null object is treated as the identity transformation (i.e. uses the parent's parameters directly for all children).; parameters - the initial parameters data passed to the inclusion_test at the root, then transformed by xform_parent_to_child for recursive calls on children.; collection_result - a pick_collector object which holds a list of interactors collected by this traversal (and optional associated data). If an object determines that it should be a part of the collection of this traversal, it should add itself to this collection by calling its report_pick() method.

flag_is_set

  public abstract boolean flag_is_set(int mask_value)

Determine if a particular bit (or bits) is set in the flag set for the interactor. In the case of testing for multiple flag bits, they must all be set to get a result of true. See interactor_consts for possible values that can be queried.

Parameters:: int - mask_value the flag bit or bits we are enquiring about.
Returns:: boolean indicating whether the bit or bits are (all) set.
See Also:: interactor_consts

constraint_flag_is_set

  public abstract boolean constraint_flag_is_set(int mask_value)

Determine if a particular bit (or bits) is set in the constraint_flag set for the interactor. In the case of testing for multiple constraint_flag bits, they must all be set to get a result of true. See interactor_consts for possible values that can be queried.

trivial_reject

  public abstract boolean trivial_reject(drawable d)

Do a trivial reject test that indicates whether the bounds of this object are entirely outside the clipping region of the given drawable object. The drawable object is assumed to be configured for our parent's coordinate system. Returns true if nothing inside our bounds will survive the clip and hence need not be drawn. This test is used in draw_self() to avoid drawing anything for the object if none of it could show up anyway.

Parameters:: drawable - d the drawable whose current clipping we are testing against.; Rectangle - bounding_box the bounding box we are comparing that with.
See Also:: draw_self

draw_self

  public abstract void draw_self(drawable d)

Draw the object's current appearance. The drawable object passed in is still set up in the parent's coordinate system. This routine normally sets up the transformation for the local coordinate system, then calls draw_self_local(). Consequently, most interactors do not override this routine, but instead override base_interactor.draw_self_local().

Parameters:: drawable - parent_d a drawable (still set up for the parent) to produce output on.
See Also:: draw_self_local

damage_self

  public abstract void damage_self(Point top_left,
                                   Dimension sz)

Indicate that the object has been modified in such as way that its appearance within the given area of the screen (expressed in local coordinates) might change and needs to be redrawn. This does not update any attributes controlling size and position of this object or any other object up the parent chain, but instead uses existing values (reflecting the existing sizes and positions). If you need to damage this object's updated position, explicitly update it first.

Parameters:: Point - top_left top left corner of the damaged rectangle.; Dimension - sz size of the damaged rectangle.

damage_self

  public abstract void damage_self(int left,
                                   int top,
                                   int wid,
                                   int hi)

Parameters:: int - left left edge of the damaged rectangle.; int - top top edge of the damaged rectangle.; int - wid width of the damaged rectangle.; int - hi height of the damaged rectangle.

damage_self

  public abstract void damage_self()

Indicate that the object has been modified in such as way that any or all of its appearance may change and its area of the screen needs to be redrawn.

damage_from_child

  public abstract void damage_from_child(interactor originator,
                                         Object user_info,
                                         Point top_left,
                                         Dimension sz)

Indicate that a change to a child (or grandchild, etc.) affects the given screen region (expressed in the coordinates of this object). This is responsible for passing damage up the tree.

Parameters:: interactor - originator the interactor that caused the damage.; Object - user_info uninterpreted information supplied by the originator at damage time.; Point - top_left top-left corner of child's damage area (in our coordinate system).; Dimension - sz size of the damage area.

damage_self

  public abstract void damage_self(interactor originator,
                                   Object user_info,
                                   Point top_left,
                                   Dimension sz)

Indicate that the object has been modified in such as way that its appearance within the given area of the screen (expressed in local coordinates) might change and needs to be redrawn. The damage may have been caused by a child (or grandchild, ...), in which case the originator parameter indicates the responsible interactor. The damage_type parameter is an uninterpreted Object reference which was supplied by the originator at the time the damage was reported.

This method does not update any attributes controlling size and position of this object or any other object up the parent chain, but instead uses existing values (reflecting the existing sizes and positions). If you need to damage this object's updated position, explicitly update it first.

Parameters:: interactor - originator the interactor that caused the damage.; Object - user_info uninterpreted information supplied by the originator at damage time.; Point - top_left top-left corner of child's damage area (in our coordinate system).; Dimension - sz size of the damage area.

damage_self

  public abstract void damage_self(Object user_info)

Indicate that the object has been modified in such as way that any or all of its appearance may change and its area of the screen needs to be redrawn.

Parameters:: Object - user_info uninterpreted information supplied by the originator at damage time.

num_feature_points

  public abstract int num_feature_points()

The number of "feature points" of an object. Feature points are points within an object which are interesting for alignment, snapping or other purposes. They are used by the move_drag and snap_drag agents.

Feature points are expressed in the local coordinates of the object in question. Objects by default provide 5 points corresponding to their corners and center. Constants representing indexes for these standard points are defined in interactor_consts. Additional points with specialized meanings may be provided by subclasses.

Returns:: int the number of feature points this object has.
See Also:: move_drag_focus_agent, move_draggable, move_drag_filter, std_drag_filters, snap_drag_agent, snap_draggable, snap_targetable, interactor_consts

feature_point

  public abstract Point feature_point(int indx)

Access to the "feature points" of an object (by index). Feature points are points within an object which are interesting for alignment, snapping or other purposes. They are used by the move_drag and snap_drag agents.

Parameters:: int - indx the index of the requested feature point.
Returns:: Point the location of the requested feature point in local coordinates.
See Also:: move_drag_focus_agent, move_draggable, move_drag_filter, std_drag_filters, snap_drag_agent, snap_draggable, snap_targetable, interactor_consts

feature_point_enabled

  public abstract boolean feature_point_enabled(int indx)

Indicate whether the indicated "feature point" of an object is considered to be enabled. Feature points are points within an object which are interesting for alignment, snapping or other purposes. They are used by the move_drag and snap_drag agents.

By default all standard feature points are always enabled. If an index out of range is given false will always be returned.

Parameters:: int - indx the index of the feature point in question.
Returns:: boolean indicating whether it is enabled.
See Also:: move_drag_focus_agent, move_draggable, move_drag_filter, std_drag_filters, snap_drag_agent, snap_draggable, snap_targetable, interactor_consts

drag_feature_point

  public abstract int drag_feature_point()

Indicate the current "feature point" of an object. This point will be used by the move_drag agent to control dragging. Feature points are points within an object which are interesting for alignment, snapping or other purposes. The current feature point is used by the move_drag agent. See that agent for complete details. Feature points are expressed in the local coordinates of the object in question. Objects by default provide 5 points corresponding to their corners and center. Constants representing indexes for these standard points are defined in interactor_consts. Additional points with specialized meanings may be provided by subclasses.

Note: this routine and the ones that use it ignore the enable status of the point as returned by feature_point_enabled(). This routine defaults to the top left corner of the object.

Returns:: the index of the current feature point.
See Also:: move_drag_focus_agent, move_draggable, move_drag_filter, std_drag_filters, interactor_consts

user_data

  public abstract Enumeration user_data()

Access to the collection of data items that we are holding for the user of this interactor. These data items are for the use of the application or user only, and are typically used to associate application specific information with a particular interactor. Data items can be entered using add_user_datum(), and deleted using remove_user_datum(). These data items are not modified by the toolkit, and can later be retrieved with this method as needed. The ordering of the data items in the returned Enumeration is not guaranteed to follow any rules, and may change between invocations.

Returns:: s Enumeration a collection of the data items attached to this interactor.
See Also:: add_user_datum, remove_user_datum

add_user_datum

  public abstract void add_user_datum(Object datum)

Adds a data item to the collection of data items that we are holding for the user of this interactor. These data items are for the use of the application or user only, and are typically used to associate application specific information with a particular interactor. Data items can be entered using this method. The same Object can be entered multiple times, and will occur in the Enumeration returned by user_data() multiple times. Data items can be deleted using remove_user_datum(). These data items are not modified by the toolkit, and can later be retrieved with user_data() as needed.

Parameters:: Object - datum the data item to associate with this interactor.
See Also:: user_data, remove_user_datum

remove_user_datum

  public abstract boolean remove_user_datum(Object datum)

Removes a data item from the collection of data items that we are holding for the user of this interactor. These data items are for the use of the application or user only, and are typically used to associate application specific information with a particular interactor. Data items can be entered using add_user_datum(), and deleted using this method. If the given Object is not associated with the interactor, no changes are made and a value of false is returned. If the given Object has been entered multiple times, only one instance is removed by invoking this method. These data items are not modified by the toolkit, and can later be retrieved with user_data() as needed.

Parameters:: Object - datum the data item to remove from association with this interactor.
Returns:: s boolean true iff successful, false if the given datum is not currently associated with this interactor.
See Also:: user_data, add_user_datum

user_info

  public abstract Object user_info()

Access to uninterpreted "user information" that we are holding for the user of this object. This information is for use of the user or application only and is typically used to associated application specific information with a particular interactor object. This information can be entered using set_user_info(). It is not modified by the toolkit, and can later be retrieved with this routine as needed.

Note that only one "user information" object can be associated with an interactor. The "user data" methods maintain a collection of objects.

Returns:: s Object the user info object attached to this interactor.
See Also:: user_data, add_user_datum, remove_user_datum
, set_user_info

set_user_info

  public abstract void set_user_info(Object user_inf)

Set the uninterpreted "user information" that we are holding for the user of this object. This information is for use of the user or application only and is typically used to associated application specific information with a particular interactor object. This information can be entered using this routine. It is not modified by the toolkit, and can later be retrieved with user_info() as needed.

Note that only one "user information" object can be associated with an interactor. The "user data" methods maintain a collection of objects.

Parameters:: Object - user_inf the object to associate with this interactor.
See Also:: user_data, add_user_datum, remove_user_datum
, user_info

set_style_lock

  public abstract void set_style_lock(boolean lock_v)

Lock or unlock the style of this interactor. When the style is locked, restyling requests are ignored.

Parameters:: boolean - lock_v new value of locked status (true == locked)

style_change

  public abstract void style_change()

Inform the interactor and all of its descendents that the global current style has changed and that they may need to restyle themselves. This should reconstruct any style-based resources used by the interactor under the new current style and recompute the size of the object and any other properties that this effects. If an interactor is style-locked, this has no effect on it. This will normally be doing a recusive traversal making calls to restyle().

See Also:: restyle

restyle

  public abstract void restyle(style new_style)

Force a restyle of the interactor under the given style. This should reconstruct any style-based resources held by the interactor under the given style, and then recompute the size of the object and any other properties that this effects. If the interactor is style-locked, this has no effect.

Parameters:: style - new_style the style to put the interactor under.

toString

  public abstract String toString()

Convert to a human readable string.

Returns:: String a human readable dump of the object.
Overrides:: toString in class Object

tag_str

  public abstract String tag_str()

Convert to a small tag string which indicates the type of interactor along with a (hopefully unique) integer (its hashCode) that can be used to identify it during debugging.

Returns:: String an terse identifying tag string for the object.

All Packages  Class Hierarchy  This Package  Previous  Next  Index