sub_arctic.style
Class style_resource_desig

java.lang.Object
  |
  +--sub_arctic.style.style_resource_desig

public class style_resource_desig

extends java.lang.Object

This class provides a style resource designator. This provides a name for a resource along with a link to a chain of fallback resources that can be substituted if this one is missing. Resource designators are registerd with, and managed by, the style_manager. The system provides a series of standard designators (which the manager itself registers). In addition, each style that provides non-standard resources is responsible for registering a designator and a fallback chain (ending at a standard designator) for each such resource. In addition, each interactor which uses non-standard resources must register a designator and fallback chain for each such resource.

In order to help avoid name conflicts conventions following the Java package naming conventions are used for constructing resource names. In particular, all non-standard resource names should be of the form: package.class:resource_name:variant where package and class refer to the class "owning" the name, resource_name describes what the resource is or is used for, and finally variant indicates one of several related resources. Standard resource names provided by the system are constructed with the special package name "#std". As an example: some of the resources for a button are:

#std.button.label_look:out #std.button.label_look:in #std.button.label_look:disabled #std.button.label_look:set

Field Summary

protected style_resource_desig	_fallback_desig Link to the first designator in the fallback chain for this designator.
protected java.lang.String	_name Name for this designator.

Constructor Summary

style_resource_desig(java.lang.String res_name)
Constructor for null fallback.

style_resource_desig(java.lang.String[] name_and_fallbacks)
String based constructor.

style_resource_desig(java.lang.String name, java.lang.String fallback)
String based constructor for special case of only one fallback.

style_resource_desig(java.lang.String res_name, style_resource_desig fallbk)
Raw constructor.

Method Summary

protected static style_resource_desig	build_fallback_chain(int indx, java.lang.String[] names) Build and return a fallback chain from the names in the given array starting at the given index.
style_resource_desig	fallback_desig() Link to the first designator in the fallback chain for this designator.
int	hashCode() Provide a hash code for this object based on its name string.
java.lang.String	name() Name for this designator.
void	set_fallback_desig(style_resource_desig fb_link) Set the link to the first designator in the fallback chain for this designator.

Methods inherited from class java.lang.Object

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

Field Detail

_name

protected java.lang.String _name

Name for this designator.

_fallback_desig

protected style_resource_desig _fallback_desig

Link to the first designator in the fallback chain for this designator.

Constructor Detail

style_resource_desig

public style_resource_desig(java.lang.String res_name,
                            style_resource_desig fallbk)

Raw constructor. This constructor provides a direct link to the first designator in its fallback chain. This is normally only used by the style manager during initialization of standard resource designators. This constructor registers the designator with the style manager. If a designator with the same name has already been registered, and that name has not been registered temporarily (as indicated by a null fallback) then an error is thrown. If a previous temporary designator has been registered its fallback is set to ours, and we are left unregistered.

style_resource_desig

public style_resource_desig(java.lang.String res_name)

Constructor for null fallback. This should only be used for building a root designator -- which normally would only be for a standard resource. (We need an extra constructor here becasue passin null for the fallback creates and ambiguity between the raw constructor and the string constructor). This constructor registers the designator with the style manager. If a designator with the same name has already been registered, and that name has not been registered temporarily (as indicated by a null fallback) then an error is thrown.

style_resource_desig

public style_resource_desig(java.lang.String[] name_and_fallbacks)

String based constructor. This constructor takes an array of strings. The first string is the name of this designator. The remaining strings in the array are the names of designators along the fallback path for this designator (which for proper operation of the system should end in the name of a standard resource designator). This constructor builds at least the first named designator, and registers it with the style manager. If a designator by the same name has already been registered (and it does not have a null designator, indicating it was registered temporarly by someone else) then an error is thrown. In addition, this constructor will also automatically create the designators for any part of the fallback path that has not yet been instantiated (naming already existing designators as part of the fallback path is not and error). However, if this designator names a fallback path that conflicts with an existing fallback path, an error be thrown.

Parameters:

String[] - name_and_fallbacks Array with the name of this designator in position 0, and the names of fallback designators in the remaining positions.

style_resource_desig

public style_resource_desig(java.lang.String name,
                            java.lang.String fallback)

String based constructor for special case of only one fallback. This constructor takes two strings. The first string is the name of this designator, the second is the name of a single fallback designator. Note: this fallback designator must have been previously created (and hence registered) or an error will be thrown. You should not normally rely on the existance of any non-standard resource designators (unless you have created them yourself).

This constructor the named designator, and registers it with the style manager. If a designator by the same name has already been registered and it has a non-null fallback (indicating it was not a temporary registration by someone else) an error is thrown.

Parameters:

String - name name of this designator

String - fallback name of fallback designator

Method Detail

name

public java.lang.String name()

Name for this designator.

Returns:

String the name string.

hashCode

public int hashCode()

Provide a hash code for this object based on its name string.

Returns:

int hash code for this object

Overrides:

hashCode in class java.lang.Object

fallback_desig

public style_resource_desig fallback_desig()

Link to the first designator in the fallback chain for this designator.

Returns:

style_resource_desig link to the next fallback designator in the fallback chain.

set_fallback_desig

public void set_fallback_desig(style_resource_desig fb_link)

Set the link to the first designator in the fallback chain for this designator. This is only allowed for "temporary" designators which were created by some object other than their owner using a null fallback (with the anticipation that the owner would later fill them in -- this allows us to not worry about who does their work first). If this method would change the fallback for a non-temporary designator, an error is thrown.

build_fallback_chain

protected static style_resource_desig build_fallback_chain(int indx,
                                                           java.lang.String[] names)

Build and return a fallback chain from the names in the given array starting at the given index. If a name indicates an existing designator with a non-null fallback, it will be returned -- ending the chain creation. If an existing designator that was registered with a null fallback is found, we will attempt to construct the remaining chain "above" it, then return it. Finally, if no matching designator is found then an entirely new chain is constructed recursively and returned.

Parameters:

int - indx index of the first name to build this chain with.

String[] - names array of designator names along the fallback path.

Returns:

style_resource_desig first resource designator in constructed fallback chain.