Back to: SceneBeans Documentation.

The SceneBeans XML File Format

The SceneBeans framework provides programmers with a convenient programming model for creating and controlling animations, and a useful set of components that can be plugged together within that framework. However, it is not practical to expect end users to write Java programs in order to define animations for use in applications, and even for experienced programmers the edit/compile/debug cycle is slow and frustrating when fine-tuning animation parameters. Therefore, we have defined an XML-based file format for animations and implemented a parser that translates XML documents into Animation objects.

The XML document type definition (DTD) used by the SceneBeans parser is relatively minimal compared to DTDs for similar applications, such as the W3C's Scalable Vector Graphics (SVG) standard. The DTD does not prescribe a limited number of component types and their options, but instead is used as a "wiring language" to describe compositions of components that the parser loads dynamically and manipulates generically with the JavaBeans APIs.

Elements

Animation

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	animation
Description	The top-level document element that contains the definition of an animation.
	width	Real	Required	n/a	The width of the animation
	height	Real	Required	n/a	The height of the animation
Contents	draw, define, behaviour, command, event, forall.

Behaviour

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	behaviour
Description	Creates a behaviour bean that can be used to animate the properties of other beans, both scene-graph nodes and other behaviours.
	algorithm	String	Required	n/a	The name of the behaviour's algorithm. This is mapped to a Java class by capitalising the first letter and searching for the class in the packages of the "behaviour" category.
	id	String	Optional	none	A symbol that uniquely identifies the behaviour bean in the document.
	event	String	Optional	none	The name of the event announced by the behaviour on completion.
Contents	param, animate, forall

Define

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	define
Attributes	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	compose, input, primitive, style, transform, paste, include, forall
Description	Creates a scene-graph fragment that is not rendered. The fragment can be linked into the rendered graph by the paste tag.

Draw

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	draw
Description	Creates a scene-graph fragment that is rendered. Multiple draw elements are composed using a Layered bean.
Attributes	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	compose, input, primitive, style, transform, paste, include, forall

Primitive

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	primitive
Description	Creates a primitive scene-graph node.
	type	String	Required	n/a	The name of the type of primitive bean. This is mapped to a Java class by capitalising the first letter and searching for the class in the packages of the "scene" category.
	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	param, animate, forall

Compose

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	compose
Description	Creates a scene-graph node that composes its sub-graphs in some manner.
	type	String	Required	n/a	The name of the type of compose bean. This is mapped to a Java class by capitalising the first letter and searching for the class in the packages of the "scene" category.
	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	param, animate, compose, input, primitive, style, transform, paste, include, forall

Style

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	style
Description	Creates a scene-graph node that changes the style (color, font etc.) in which its sub-graphs are rendered. Multiple sub-graphs are composed using a Layered bean.
	type	String	Required	n/a	The name of the type of compose bean. This is mapped to a Java class by capitalising the first letter and searching for the class in the packages of the "scene" category.
	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	param, animate, compose, input, primitive, style, transform, paste, include, forall

Transform

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	transform
Description	Creates a scene-graph node that applies an affine transformation to the coordinate space of its sub-graphs. Multiple sub-graphs are composed using a Layered bean.
	type	String	Required	n/a	The name of the type of compose bean. This is mapped to a Java class by capitalising the first letter and searching for the class in the packages of the "scene" category.
	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	param, animate, compose, input, primitive, style, transform, paste, include, forall

Input

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	input
Description	Defines a portion of the scene-graph as being sensitive to some form of user input, as defined by the type parameter. Multiple sub-graphs are composed using a Layered bean, and are all marked as sensitive.
	type	String	Required	n/a	The name of the type of compose bean. This is mapped to a Java class by capitalising the first letter and searching for the class in the packages of the "scene" category.
	id	String	Optional	none	A symbol that uniquely identifies the scene bean in the document.
Contents	param, animate, compose, input, primitive, style, transform, paste, include, forall

Paste

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	paste
Description	Creates a link to a previously defined scene-graph node. The linked node can either be created by a define element, or be part of the visible scene-graph within a draw tag. This allows the construction of directed, acyclic graphs, rather than just trees.
Attributes	object	String	Required	n/a	The identifier of a scene-graph node previously defined in the document and named by an id attribute.
Contents	empty

Include

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	include
Description	Includes an animation defined in another XML document. The element may include param elements that define macros used to expand attribute values in the included document.
Attributes	src	URL	Required	n/a	The URL of the animation to include. The URL may be specified relative to that of the the current document.
Contents	param

Param

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	param
Description	The param tag has two uses, to set the value of Java Bean properties of behaviours and scene-graph nodes, and to define macros when including another animation document.
	name	String	Required	n/a	The name of the property
	value	varies	Required	n/a	The value of the property. The value attribute is parsed according to the type of the property being configured.
Contents	empty

Animate

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	animate
Description	Animates a Java Bean property of a behaviour or scene-graph node. A single parameter can be animated by multiple behaviours, but the resulting animation is undefined if multiple behaviours are active at any one time.
	param	String	Required	n/a	The name of a Java Bean property to animate.
	behaviour	String	Required	n/a	The identifier of a behaviour bean previously defined in the document and named by an id attribute.
	facet	String	Optional	no facet	The facet of the behaviour. If this is not specified, then the behaviour is assumed not to be facetted.
Contents	empty

Command

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	command
Description	Defines how an animation reacts to the named command.
Attributes	name	String	Required	n/a	The name of the command.
Contents	set, start, stop, reset, announce, invoke, forall

Event

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	event
Description	Defines how an animation reacts to a named event announced by one of its constituent beans.
	event	String	Required	n/a	The name of the event.
	object	String	Required	n/a	The identifier of a scene-graph node previously defined in the document and named by an id attribute.
Contents	set, start, stop, reset, announce, invoke, forall

Set

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	set
Description	Defines that the animation changes the value of a bean property in response to receiving an event or command. This can be applied to both behaviour beans and scene-graph nodes.
	object	String	Required	n/a	The identifier of a scene-graph node previously defined in the document and named by an id attribute.
	param	String	Required	n/a	The name of the parameter to be set.
	value	varies	Required	n/a	The new value of the parameter.
Contents	empty

Start

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	start
Description	Defines that the animation starts the named behaviour in response to receiving an event or command. This only works if the behaviour is an Activity.
Attributes	behaviour	String	Required	n/a	The identifier of a behaviour bean previously defined in the document and named by an id attribute.
Contents	empty

Stop

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	stop
Description	Defines that the animation stops the named behaviour in response to receiving an event or command. This only works if the behaviour is an Activity.
Attributes	behaviour	String	Required	n/a	The identifier of a behaviour bean previously defined in the document and named by an id attribute.
Contents	empty

Reset

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	reset
Description	Defines that the animation resets the named behaviour in response to receiving an event or command. This only works if the behaviour is an Activity.
Attributes	behaviour	String	Required	n/a	The identifier of a behaviour bean previously defined in the document and named by an id attribute.
Contents	empty

Announce

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	announce
Description	Defines that the animation announces a named event in response to receiving an event or command.
Attributes	event	String	Required	n/a	The name of the event.
Contents	empty

Invoke

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	invoke
Description	Defines that the animation invokes a command in response to receiving an event or command. The command invoked may be defined by the animation or be a command provided by an included animation
	name	String	Required	n/a	The name of the command.
	object	String	Optional	The current animation	The id of the object on which to invoke a command. This only applies to included animations, not to behaviour or scene-graph beans.
Contents	empty

Forall

Attributes	Name	Type	Optional/Required	Default Value	Description
Element	forall
Description	The forall element is used for macro expansion of attribute values and iteration. A macro variable defined by a forall element is replaced within all attribute values in the elements within the forall element. Giving the macro multiple values will make the SceneBeans' XML processor translate the contents of the forall element multiple times, once for each value. Macros are expanded with the syntax "${variable}". Unlike Unix shell languages, the braces are mandatory. The "\" character is used to escape macro syntax: it is replaced by the next character in the string. Macro expansion can specify a default value to be used if the macro is not defined, using the syntax "${variable=default}". This can be used to parameterise animation documents.
	var	String	Required	n/a	The name of the macro.
	values	String	Required	n/a	The values that the macro may take, separated by delimiter characters. Forall elements that define multiple values for a macro are processed multiple times - once for each value - and the macro variable is replaced with a different value each iteration. Delimiter characters may be specified using the "sep" attribute.
	sep	String	Optional	Whitespace characters: space, tab and newline.	The characters used to separate each value.
Contents	Any element that can contain other elements. The only elements that are permissable within the forall element are those that are permissable within its parent.

Processing Instructions

Attributes	Name	Type	Optional/Required	Default Value	Description
Instruction	scenebeans
Description	The <?scenebeans?> processing instruction is used to load additional packages of beans. This allows the namespace of scene-graph node types and behaviour algorithms to be extended on a per-document basis.
	category	"behaviour" or "scene".	Required	n/a	The category of bean.
	package	String	Required	n/a	The name of the package in which bean classes may be found.
	codebase	URL	Required	n/a	A URL from which Java classes may be loaded. If the URL ends with a "/", it is assumed to refer to a directory containing the root of the package tree, and class files are loaded from its subdirectories. Otherwise the URL is assumed to refer to a JAR file containing the classes. The URL may be specified relative to that of the the current document.