sub_arctic.style
Class composer

java.lang.Object
  |
  +--sub_arctic.style.composition_part_base
        |
        +--sub_arctic.style.composer

public class composer
extends composition_part_base
implements composer_consts

This class provides an object which is capable of composing images from sub-parts. It is used by the style system to create images for a variety of different interactors, based on simple style independent specifications. These specifications are combined with style specific resources (such as images) as well as instance specific information (such as a string for a label) to create the final look of an interactor.

Image creation is performed on the basis of a series of objects drawn in some order. Typically, the first object is a background object (a "blank"), and the remaining objects are a series of parts (which can be images, text, invisible "anchor points", or other completed compositions). Each composed object is placed (and possibly sized) by a "placement rule". Each placement rule indicates one coordinate of the position or size of a part and contains an equation which computes that value from the size or position of other parts. Placement rules may also make use of one or more style specific resources or instance specific parameters. Parameters provide information about the specific object being constructed (such as text strings or sizes). Style specific resources provide values such as style specific part images, objects for rendering text in special ways, and/or spacing values.

By separating out the rules for placement from the actual look of the parts placed (and providing a good library of parts and sub-parts in each style), it is possible in many cases to create specifications for interactor appearance that can be applied with styles that did not exist when the interactors were first built, and to create new interactors under an existing style without extending it.

The lifecycle of a composer has several phases. Composers are first initialized by providing a set of tables that drive their behavior. At this stage the composer is both style and instance independent. Once created a composer object must be provided with style and instance information (by calling compose()) in order to be drawn. Note that many operations (e.g., drawing) are not available until compose() has been called, and several operations are only valid during the composition process itself. Compose() may be called multiple times with different style and instance information in order to produce a "restyled" image.


Field Summary
protected  int[] _expected_parm_types
          Set of indicators for expected parameter types.
protected  int _h
          Height of the composed result.
protected  java.lang.Object[] _parameters
          Parameters being used to compose with.
protected  int[] _part_spec_table
          Table describing how to create each part of the composition.
protected  composition_part[] _parts
          Array that holds all of our parts.
protected  style _providing_style
          Style that we are getting resources from.
protected  java.lang.Object[] _resource_cache
          Cache of resources we have previously looked up from the providing style.
protected  java.lang.Object[] _resource_names
          Set of resource names or designators for the resources we expect to get from a style when composed.
protected  comp_placement_rule[] _rules
          The rules for computing the positions and sizes of each part.
protected  int _w
          Width of the composed result.
protected static int H_COORD
          Constant for designating h coord.
protected  boolean[] part_in_process
          This array indicates whether various coordinates of each part are currently being computed in order to detect cycles.
protected  boolean[] part_up_to_date
          This array indicates whether various coordinates of each part have been computed and are up-to-date.
protected static int W_COORD
          Constant for designating w coord.
protected static int X_COORD
          Constant for designating x coord.
protected static int Y_COORD
          Constant for designating y coord.
 
Fields inherited from class sub_arctic.style.composition_part_base
_feature_points, _x, _y
 
Constructor Summary
composer(int[] exp_types, java.lang.Object[] res_names, int[] part_specs, comp_placement_rule[] ruls)
          Full constructor.
 
Method Summary
protected  void check_parm(int indx, int expected_type)
          Check whether the parameter or resource is the type we expect.
protected  void check_parms(java.lang.Object[] actual_parms)
          Check whether the set of parameters matches what is expected.
static void check_type(int expected_type, java.lang.Object actual_parm, int obj_n)
          Check whether a given parameter or resource object is the type we expect.
 void compose(java.lang.Object[] parms, style prov_style)
          Create a new layout given a set of parameter values.
protected static java.lang.String coord_name(int coord_num)
          Return the name of the given coordinate as a string.
 void draw_self(drawable on_surf, int at_x, int at_y)
          Draw the object on the given drawing surface at the given location. Note: this will produce useful results only if compose() has already been called to establish a layout.
protected  int eval_coord(int part_num, int coord_num)
          Return an up-to-date value for one of the coordinates of the given part number.
protected  int eval_h(int part_num)
          Return an up-to-date value for the height of the given part number.
protected  int eval_w(int part_num)
          Return an up-to-date value for the width of the given part number.
protected  int eval_x(int part_num)
          Return an up-to-date value for the x position of the given part number.
protected  int eval_y(int part_num)
          Return an up-to-date value for the y position of the given part number.
 int get_int_parm(int index)
          Get the int value of the parameter whose index is given.
 java.lang.Object get_parm(int index)
          Get the value of the parameter whose index is given.
 int get_part_coord(int part_num, int coord)
          Get the up-to-date value of the given coord of the part whose number is given.
 java.lang.Object get_resource(int index)
          Get the object coresponding to a given resource index.
 int h()
          Height of the composed result.
protected  composition_part instantiate_part(int create_type, int parm_1, int parm_2)
          Instantiate a composition part based on a part specification.
protected  void instantiate_parts()
          Instantiate parts to be composed from a set of parameters.
 styled_image make_image()
          Create an image for the composition.
 styled_image make_image(java.lang.Object[] parms, style prov_style)
          Call compose() with the given parameters and style to produce a layout, then create an image for the composition and return it.
protected static java.lang.String part_mk_name(int part_mk_indicator)
          Provide human readable string for a part type (one of the MK_PART_* constants).
 java.lang.String toString()
          Convert to human readable string for debugging dump.
static boolean type_is_ok(int expected_type, java.lang.Object actual_parm)
          Check whether a given parameter or resource object is the type we expect.
protected static java.lang.String type_name(int type_indicator)
          Provide human readable string for a type.
 int w()
          Width of the composed result.
 
Methods inherited from class sub_arctic.style.composition_part_base
can_set_h, can_set_w, feature_point, num_feature_points, set_feature_points, set_h, set_w, set_x, set_y, x, y
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_expected_parm_types

protected int[] _expected_parm_types
Set of indicators for expected parameter types. The size of this array will determine how many parameters we expect.

_resource_names

protected java.lang.Object[] _resource_names
Set of resource names or designators for the resources we expect to get from a style when composed. This array should only hold objects of type String or style_resource_desig. This array will also be used to determine how many style specific resources we expect.

_part_spec_table

protected int[] _part_spec_table
Table describing how to create each part of the composition. Each part is described by 3 integer values. The first is one of the MK_PART_* constants and indicates what method is used to construct the part. The second and third values indicate parameter or style resource numbers that are used to to provide values for constructing the part (for some creation methods, one or both of these may be ignored). Parameter numbers are indicated by simple non-negative indexes. Resource numbers are indicated by negative values which can be converted to indexes by negation and then subtraction of 1.

_parts

protected composition_part[] _parts
Array that holds all of our parts. This is normally filled in by instantiate_parts() and will not be useful until after composition.
See Also:
instantiate_parts()

X_COORD

protected static final int X_COORD
Constant for designating x coord.

Y_COORD

protected static final int Y_COORD
Constant for designating y coord.

W_COORD

protected static final int W_COORD
Constant for designating w coord.

H_COORD

protected static final int H_COORD
Constant for designating h coord.

part_up_to_date

protected boolean[] part_up_to_date
This array indicates whether various coordinates of each part have been computed and are up-to-date. Indications for the x, y, width, and height of a given part are found at: n*4+X_COORD, n*4+Y_COORD, n*4+W_COORD, and n*4+H_COORD, respectively. Note: storage is only allocated for this during placement.

part_in_process

protected boolean[] part_in_process
This array indicates whether various coordinates of each part are currently being computed in order to detect cycles. Indications for the x, y, width, and height of a given part are found at: n*4+X_COORD, n*4+Y_COORD, n*4+W_COORD, and n*4+H_COORD, respectively. Note: storage is only allocated for this during placement.

_rules

protected comp_placement_rule[] _rules
The rules for computing the positions and sizes of each part. Rules for the x, y, width, and height of a given part are found at: n*4+X_COORD, n*4+Y_COORD, n*4+W_COORD, and n*4+H_COORD, respectively. Null rules are allowed. These indicate that the part maintains or computes this value itself (intrinsically) and hence there is no rule for computing it.

_parameters

protected java.lang.Object[] _parameters
Parameters being used to compose with. This will only be valid during to compose().

_resource_cache

protected java.lang.Object[] _resource_cache
Cache of resources we have previously looked up from the providing style. This will only have valid entries (and only be allocated) during compose(). The prefered way to access these values is through get_resource() since that will automatically fetch and cache what it needs.

_providing_style

protected style _providing_style
Style that we are getting resources from. This is only valid during a call to compose().

_w

protected int _w
Width of the composed result. Note this does not hold a valid value until the object has actually been composed.

_h

protected int _h
Height of the composed result. Note this does not hold a valid value until the object has actually been composed.
Constructor Detail

composer

public composer(int[] exp_types,
                java.lang.Object[] res_names,
                int[] part_specs,
                comp_placement_rule[] ruls)
Full constructor.
Parameters:
int[] - exp_types an array indicating the type of each expected parameter to this composition.
Object[] - res_names array of String or style_resource_desig objects indicating the resources that should be provided later by a style.
int[] - part_specs an array of integers indicating how to construct each part of this composition. This array will have three entries for each part. The first indicates how to construct the part, the remaining two are parameters to that construction (see instantiate_part() for a full description of how these values are used).
comp_placement_rule[] - ruls an array of constraints on the x, y, w, and h coordinate of each part.
See Also:
instantiate_part(int, int, int)
Method Detail

type_name

protected static java.lang.String type_name(int type_indicator)
Provide human readable string for a type.
Parameters:
int - type_indicator the type constant to print

type_is_ok

public static boolean type_is_ok(int expected_type,
                                 java.lang.Object actual_parm)
Check whether a given parameter or resource object is the type we expect.
Parameters:
int - expected_type indicator constant for what we expect to see.
Object - actual_parm the actual object we are checking.
Returns:
boolean indicating whether we pass the test.

check_type

public static void check_type(int expected_type,
                              java.lang.Object actual_parm,
                              int obj_n)
Check whether a given parameter or resource object is the type we expect. If it is not the proper type an error is throw, otherwise we just return. Parameter numbers are given as simple non-negative indexes. Resource numbers are given as negative numbers, which can be converted to indexes by negating the value then subtracting 1.
Parameters:
int - expected_type indicator constant for what we expect to see.
Object - actual_parm the actual object we are checking.
int - obj_n positive index of the parameter we are checking, or negative value indicating resource

check_parm

protected void check_parm(int indx,
                          int expected_type)
Check whether the parameter or resource is the type we expect. If it is not the proper type an error is throw, otherwise we just return. Parameters are given as simple non-negative indexes. Resource nubmers are encoded as negative values where the index can be found by negation and subtraction of 1. Note: this routine must only be called during composition.
Parameters:
int - expected_type encoding of the type we expect
int - indx encoding for parameter/resource we are checking;

check_parms

protected void check_parms(java.lang.Object[] actual_parms)
Check whether the set of parameters matches what is expected. This throws an error if we see something other than expected, otherwise it returns.
Parameters:
Object[] - actual_parms the parameters to be checked.

part_mk_name

protected static java.lang.String part_mk_name(int part_mk_indicator)
Provide human readable string for a part type (one of the MK_PART_* constants).
Parameters:
int - type_indicator the type constant to print

instantiate_part

protected composition_part instantiate_part(int create_type,
                                            int parm_1,
                                            int parm_2)
Instantiate a composition part based on a part specification. Part specifications are taken from the part_spec_table and consist of 3 values: a constant indicating how the part is created, and two parameter numbers indicating where to get values for constructing the part (for some creation methods, one or both of these may be ignored). Parameter numbers are indicated by simple non-negative indexes. Resource numbers are indicated by negative values which can be converted to indexes by negation and then subtraction of 1.

Parameters are used as follows:

MK_PART_COPY
parm_1 is the parameter/resource number to copy from.
MK_PART_TEXT
parm_1 should be the number of a text_renderer parameter/resource object, and parm_2 the number of a String parameter/resource.
MK_PART_IMAGE
parm_1 should be the number of a parameter/resource containing a loaded_image.
MK_PART_POINT
both parameters are ignored.
MK_PART_BLANK, MK_PART_INT_W_BLANK, MK_PART_INT_H_BLANK, or MK_PART_INT_WH_BLANK
parm_1 should be the number of a blank object parameter/resource from which this part should be cloned. These values differ in how constraints on their width and/or height are used (but not how the part is instantiated). For the MK_PART_INT_*_BLANK values one or both of the width or height constraints will be refering to the internal width or height of the object, rather than the normal external size.

Note: this method should only be invoked from within a call to compose() since it assumes that the parameters, and resource cache have been established and this is only true while composition is happening.

Parameters:
int - create_type MK_PART_* constant indicating the type of part to be created.
int - parm_1 encoding of the first parameter/resource object number to be used for creation of the part.
int - parm_2 encoding of the second parameter/resource object number to be used for creation of the part.
Returns:
composition_part the part created.

instantiate_parts

protected void instantiate_parts()
Instantiate parts to be composed from a set of parameters. This is driven from the part_spec_table and a set of parameters and places its results in a newly created array in the _parts instance variable. Note: this should only be called during composition.

coord_name

protected static java.lang.String coord_name(int coord_num)
Return the name of the given coordinate as a string.
Parameters:
int - coord_num coordinate index (should be X_COORD, Y_COORD, W_COORD, of H_COORD).
Returns:
String string for name of coordinate.

eval_coord

protected int eval_coord(int part_num,
                         int coord_num)
Return an up-to-date value for one of the coordinates of the given part number. Valid coord_num values are: X_COORD, Y_COORD, W_COORD, and H_COORD denoting x, y, w, and h, respectively.
Parameters:
int - part_num the part we are requesting a value for.
int - coord_num the coordinate within that part we are requesting a value for. Valid values are: X_COORD, Y_COORD, W_COORD, and H_COORD denoting x, y, w, and h, respectively.

eval_x

protected int eval_x(int part_num)
Return an up-to-date value for the x position of the given part number.
Parameters:
int - part_num the part we are requesting the position for.

eval_y

protected int eval_y(int part_num)
Return an up-to-date value for the y position of the given part number.
Parameters:
int - part_num the part we are requesting the position for.

eval_w

protected int eval_w(int part_num)
Return an up-to-date value for the width of the given part number.
Parameters:
int - part_num the part we are requesting the width for.

eval_h

protected int eval_h(int part_num)
Return an up-to-date value for the height of the given part number.
Parameters:
int - part_num the part we are requesting the height for.

get_part_coord

public int get_part_coord(int part_num,
                          int coord)
Get the up-to-date value of the given coord of the part whose number is given. The requested value will be evaluated if necessary before it is returned. The coordinate can be one of LEFT, RIGHT, HCENTER, TOP, BOTTOM, VCENTER, WIDTH, or HEIGHT, (or for blanks only, INTERIOR_X, INTERIOR_Y, INTERIOR_WIDTH, or INTERIOR_HEIGHT) or it may be constructed from a feature point number (FPN) using either "(FPN << FEATURE_SHIFT) | FEATURE_X" or "(FPN << FEATURE_SHIFT) | FEATURE_Y", to indicate the x or y coordinate of a feature point respectively.
Parameters:
int - part_num the number of the part that a value is being requested from.
int - coord a designator value for a coordinate value within the given part.
Returns:
int the up-to-date value that was requested.

get_parm

public java.lang.Object get_parm(int index)
Get the value of the parameter whose index is given. If the index is out of range an error is thrown. Note: this may only be called during a call to compose(). If this is called outside that situation, an error will be thrown.
Parameters:
int - index the number of the parameter we are requesting.
Returns:
int that parameter's value.

get_int_parm

public int get_int_parm(int index)
Get the int value of the parameter whose index is given. If the index is out of range or the parameter does not have an Integer value an error is thrown. Note: this may only be called during a call to compose(). If this is called outside that situation, an error will be thrown.
Parameters:
int - index the number of the parameter we are requesting.
Returns:
int that parameter's value.

get_resource

public java.lang.Object get_resource(int index)
Get the object coresponding to a given resource index. This maintains a cache of these objects in _resource_cache. This should only be called during composition.
Parameters:
int - index the index of the resource we want
Returns:
Object the given resource

w

public int w()
Width of the composed result. Note this does not provide a valid value until the object has actually been composed.
Returns:
int the width of this object.
Overrides:
w in class composition_part_base

h

public int h()
Height of the composed result. Note this does not provide a valid value until the object has actually been composed.
Returns:
int the height of this object.
Overrides:
h in class composition_part_base

compose

public void compose(java.lang.Object[] parms,
                    style prov_style)
Create a new layout given a set of parameter values.
Parameters:
Object[] - parms an array of objects which serve as parameters to the composition. If these do not match the expected types an error is thrown.
style - prov_style style providing resources for this composition

make_image

public styled_image make_image(java.lang.Object[] parms,
                               style prov_style)
Call compose() with the given parameters and style to produce a layout, then create an image for the composition and return it.
Parameters:
Object[] - parms an array of objects which serve as parameters to the composition. If these do not match the expected types an error is thrown.
style - prov_style style providing resources for composition.
Returns:
styled_image the resulting image (note: we do not fill in the style information in this image).

make_image

public styled_image make_image()
Create an image for the composition. Note: this only produces useful results if compose() has already been called to establish a layout.
Returns:
styled_image the resulting image (note: we do not fill in the style information in this image).

draw_self

public void draw_self(drawable on_surf,
                      int at_x,
                      int at_y)
Draw the object on the given drawing surface at the given location.

Note: this will produce useful results only if compose() has already been called to establish a layout. Also beware that many composers are shared, so you must be certain that other users of the same object have not re-composed it before it is drawn.

Parameters:
drawable - on_surf the drawing surface to draw on.
int - at_x the x location to draw at.
int - at_y the y location to draw at.
Overrides:
draw_self in class composition_part_base

toString

public java.lang.String toString()
Convert to human readable string for debugging dump.
Returns:
String A multi-line debug dump of the object.
Overrides:
toString in class composition_part_base