org.web3d.x3d.sai
Interface MFString

All Superinterfaces:

MField, X3DField

public interface MFString
extends MField

Representation of a MFString field.

Strings are represented using standard java.lang.String representations. The implementation of this class will provide any necessary conversions to the UTF8 format required for VRML support.

Version:

1.0 30 April 1998

Method Summary

void	append(java.lang.String value) Places a new value at the end of the existing value, increasing the field length accordingly.
void	clear() Removes all values in the field and changes the field size to zero.
java.lang.String	get1Value(int index) Get a particular string value in the given eventOut array.
void	getValue(java.lang.String[] value) Write the value of the array of the strings to the given array.
void	insertValue(int index, java.lang.String value) Inserts a value into an existing index of the field.
void	removeValue(int index) Removes one value from the field.
void	set1Value(int index, java.lang.String value) Set a particular string value in the given eventIn array.
void	setValue(int numStrings, java.lang.String[] value) Set the value of the array of strings.

Methods inherited from interface org.web3d.x3d.sai.MField

getSize

Methods inherited from interface org.web3d.x3d.sai.X3DField

addX3DEventListener, getDefinition, getUserData, isReadable, isWritable, removeX3DEventListener, setUserData

Method Detail

append

void append(java.lang.String value)

Places a new value at the end of the existing value, increasing the field length accordingly.

Parameters:

value - The value to append

clear

void clear()

Removes all values in the field and changes the field size to zero.

getValue

void getValue(java.lang.String[] value)

Write the value of the array of the strings to the given array. Individual elements in the string array may be null depending on the implementation of the browser and whether it maintains null references.

Parameters:

value - The string array to be filled in

Throws:

java.lang.ArrayIndexOutOfBoundsException - The provided array was too small

get1Value

java.lang.String get1Value(int index)

Get a particular string value in the given eventOut array.

If the index is out of the bounds of the current array of data values an ArrayIndexOutOfBoundsException will be generated. If the array reference was null when set, an empty string will be returned to the caller.

Parameters:

index - The position to get the string value from

Returns:

The string value

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index value was out of bounds of the current array.

insertValue

void insertValue(int index,
                 java.lang.String value)
                 throws java.lang.ArrayIndexOutOfBoundsException

Inserts a value into an existing index of the field. Current field values from the index to the end of the field are shifted down and the field length is increased by one to accomodate the new element. If the index is out of the bounds of the current field an ArrayIndexOutofBoundsException will be generated.

Parameters:

index - The position at which to insert

value - The new element to insert

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index was outside the current field size.

removeValue

void removeValue(int index)
                 throws java.lang.ArrayIndexOutOfBoundsException

Removes one value from the field. Values at indices above the removed element will be shifted down by one and the size of the field will be reduced by one.

Parameters:

index - The position of the value to remove.

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index was outside the current field size.

setValue

void setValue(int numStrings,
              java.lang.String[] value)

Set the value of the array of strings. If value[i] contains a null referenc this will not cause an exception to be generated. However, the resulting event that the eventIn receives will be implementation specific as this is not dealt with in the VRML specification.

Parameters:

numStrings - The number of items to be copied from this array

value - The array of strings.

set1Value

void set1Value(int index,
               java.lang.String value)

Set a particular string value in the given eventIn array. To the VRML world this will generate a full MFString event with the nominated index value changed.

If the index is out of the bounds of the current array of data values an ArrayIndexOutOfBoundsException will be generated. If the value reference is null then the result is implementation specific in terms of the array reference that reaches the eventIn. In any case, an event will reach the destination eventIn, but the values in that array are implementation specific. No exception will be generated in this case.

Parameters:

index - The position to set the string value

value - The string value

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index value was out of bounds of the current array.