|
|||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
3. Turbine Media Markup Language This chapter describes the very powerful Turbine MML language that allows you to create a variety of multimedia elements. A good number of examples is included while the reference for all tags available on the MML Reference section.
Turbine Media Markup Language is an XML language that models all the possible multimedia elements inside Turbine, from text, images and shapes to audio and video, as well as complex commands like charts and automedia. MML is pervasive across Turbine, it can be used both from text MML templates as well as from inside Flash .swf template files. Turbine MML specifies where and when elements are placed, moved or removed. An example of MML that displays text, starts playing an MP3 and creates a movie clip with two images:
In general, white space characters are ignored by the MML parser, except on places where they can be important, for example on text elements. MML shares certain characteristics with HTML - for example, colors are specified in the traditional HTML form #RRGGBB or in the form #AARRGGBB, where AA is an extra alpha component.
Placing Elements on the Screen Turbine MML is in part about describing where and when to display media elements, like text audio or video. Elements are placed in a screen with left-to-right X-axis values and top-to-bottom Y-axis values - horizontal coordinates increase to the right, vertical coordinates increase downwards, with all values in pixels:
For example to display an image at position 20,20 we can use the pos attribute, which is common to all visual tags:
The coordinates origin, the point (0,0) is on the top-left corner of the media being generated. Certain elements like movie clips, buttons and shapes create their own coordinate spaces, which means that the location where those elements are placed represents the origin for any elements that are placed inside them (their 0,0) - this happens because those elements can contain other elements inside themselves. For example suppose this movie clip placed at position 100,100:
Inside this movie clip, an image is placed at position 20,20 - since the image is inside the movie clip and thus should use its coordinate system, the image is in fact placed at 100+20, 100+20 that is at global position 120,120. What happens is that elements placed inside the movie clip relate to the position where the movie clip is placed as being their origin, as their 0,0 point. Besides
x and y coordinates, elements can be placed at different depth values,
so that some elements are above or below other elements. The depth of
an element is a numeric value, where higher values mean that the element
was placed "higher", with respect to elements placed on lower
depths. By default and if not specified, depth values continuously go
up - that is an element placed after another element will be immediately
above it.
Elements should always be placed at separated depths, so that each element is on its own depth, to avoid confusions. Most of the time, automatic depth values are used, so this is not a problem. But when numeric depth values need to be specified, and to make things easier, it's possible to use depth aliases for those numbers - a depth alias is a name that refer to a certain depth, instead of numeric values. On the next example the image and text elements will appear at the same depth:
The first
time a non-numeric value is used in a depth attribute, it defines that
depth as being that alias. Later the alias can be used to refer to that
depth. Depth aliases are thus a convenience to structure element depths,
avoiding the need to specify numeric depths. Placing Elements Across Frames On a multimedia environment such as Turbine, besides positioning elements spatially, it's also necessary to distribute them across time - to place them, remove them or change their position across the frames on a timeline. Each of these frames display for a certain duration of time, with all frames having the same duration - this duration is set by the frame rate at which the generated movie plays. Besides the main timeline, each movie clip has its own timeline, with frames from all timelines displaying synchronized - that is having the same frame rate and displaying at the same instant. By default, successions of frames are displayed in a continuous loop, with the screen always starting in a cleared state (with no elements placed) on the first frame. However, the "frame" and "frame rate" concepts apply in different ways to a PDF document. The "frame rate" concept is completely eliminated but the "frame" concept is translated to a PDF page. When outputting to PDF, one would end with a PDF document with as many pages as existing frames in the input media. Some examples:
Besides placing elements across frames, one must be able to move and remove them where necessary. This can be accomplished with the <Move> and <Remove> tags. Move tags deal with depth values - you can move whatever element is at a specified depth. On the next example, an image, which is at depth 10, displays for two frames at position 100,100 and is then moved to a different position (200,200) for another two frames.
Besides changing the position, the <Move> tag can in fact change any other attributes of an element - known as the common <place> attributes. The Remove tag, removes an element placed at a certain depth. For example on the next example, an image displays for three frames at depth 10 and is then removed from the screen:
As in the <Move> tag, the elements to remove must be referenced by their depth values. A special case of the <Remove> tag is when it is used without a depth attribute - on this case all the visible elements (elements previously placed) are removed from the screen. On the next example, two text blocks display for two frames are then removed and substituted by a new text block:
So far we've seen examples of element placing, with the pos and depth attributes - these two attributes are part of a family of attributes that are common to all visual tags, to tags that can be placed on the screen. The most interesting of these common attributes are:
These attributes are very important for element composition, because they can express a variety of effects: size changes, rotations, transparency and many others. The id attribute can be used on any element to specify that the element can later be used, for example to be placed several times into different positions or frames, through the <Place> tag. The id attribute works as the unique identity for the element, allowing for reuse of the element on multiple situations. On the next example, the logo-image.tiff image is loaded on the <Image> tag, displayed and assigned to the id "logo"; later it is placed three more times on distinct positions by the <Place> tags, by using the "logo" id attribute:
What if we wanted to define the image on the <Image> tag, but did not want to display it at that time? This can be accomplished by adding a flags attribute set to "define". An interesting
side-efect of the id attribute is that in Flash it exports the element
into Action Script, making it available for later manipulation at player-time.
This is equivalent to enabling the "Linkage Properties" on
the Macromedia Flash editor, to be used with methods like MovieClip.AttachMovie
or Sound.AttachSound. The Instance Common Attribute While the
id attribute is a server-side identifier of the element that allows
placement of multiple copies of such element, the instance attribute
is instead a Flash player-time identification of element instances.
In the Flash player, a Turbine element with the instance attribute set,
can be referenced from Flash Action Script as a regular instance.
Through
the instance attribute, elements can be composed inside Turbine and
then made available for direct Action Script manipulation on the Flash
player. The <Media> tag is an optional top-level tag that can specify properties of the media being generated - properties like the frame rate, native size, background color or compression settings. The next example shows a <Media> tag specifying a native size of 400 x 300 against a blue background:
Most of
the attributes available on the <Media> tag map into the {Media.*}
special variables. Turbine includes sophisticated text layout capabilities accessible through a very simple HTML 1.0-like interface. There are two types of text elements:
Static
text is thus best fitted for non-changing code that complex layout/formatting,
while dynamic text can be used for more "dynamic" purposes. Text Tag The <Text> tag creates static text blocks with the several options, most of which can be defined for the whole text block or down to paragraphs and individual characters:
Most of these characteristics can either be specified for the whole block as attributes of the <Text> tag:
- Or they can be specified inside the <Text> tag, as HTML-like formatting tags, allowing for fine granularity:
For the tags possible inside a <Text> tag, please see the Text Tags section on the MML reference. By using the bounds attribute, a number of rectangular areas can be specified, across which the text will flow. The general rule is that text will always flow from the top to the bottom, trying to fit the next available flow area. For example, the following text displays first across a rectangular area, and then down across a thin right-side rectangle (of 100 pixels, between left=500 and right=600):
The <TextField> tag can display a dynamic or editable text block - the following options can be used when outputting to Flash:
When outputting to PDF, there are some limitations associated with text fields:
Because of the above limitations, when outputting text to PDF, it is generally advisable to use static text instead of text fields whenever possible, because of its extra flexibility. An example of the <TextField> tag is:
As in the <Text> tag, <TextField> can also be used with an src attribute, to load its contents from an external file or remote HTTP location:
The <Shape> tag and its inner tags allow the drawing of shape elements, from a set of commands to select line and fill styles, draw lines and curves, or draw graphic elements like rectangles or circles. Next is an example of a circle shape with a radius of 50 pixels, centered at 100,100 and filled with a semi-transparent red:
The next
sections describe the capabilities of the different Shape tags. The
reference for all the <Shape> tags is available here. Fill and Line Style Shape Tags Shapes
can be rendered using a Line Style describing the thickness and color
to use, and a Fill Color that basically tells the type of paint to use
for the enclosed areas of a shape. For example, to draw a blue line
with a thickness of 5 pixels, a Line Style command must be issued prior
to this Line command - afterwards all commands that need to draw lines
will use the last defined Line Style command; the same applies for Fill
Style definitions.
Line and Curve Shape Tags Two types of lines are possible - straight and curved lines:
Graphic Shape Tags Besides simple lines, tags are available to display other common graphic shapes like:
Through the <Image> tag, Turbine can load external images from local files or remote HTTP locations in the following formats:
Displaying an image at a size of 200x160 pixels, through the size attribute is very simple:
A number of interesting things can be done with images, through the attributes of this tag:
Turbine
will always try to reuse multiple equal images to optimize the generated
file size. Created
with the <MovieClip>
tag, movie clips are the basic unit of time organization, allowing elements
to be sequenced across time. Movie clips provide a base where a succession
of frames (through the <Frame>
tag) are displayed - on these frames elements can be placed, changed
or removed as needed. Frames always have the same duration, which is
specified by the global frameRate setting (available on the {Media.FrameRate}
variable or through the Interface).
Please see the above 'Placing Elements Across Frames' section for an overview and examples of movie clips.
Button elements created with the <Button> tag, can be used to create clickable hot-spots for anything from normal buttons to dragging areas and a lot more. A simple example of a button displaying an image with a text above it; when clicked, a URL is requested; when the mouse enters the button area, a wash.wav audio file is played:
On the example we can see button states expressed through the <State> tag; as well as button events, signaled on the event attribute of the <Script> and <Audio> tags. Button States Button states describe how the button will appear on the four possible states:
A button state is specified by the <State> tag, which can express one or more of these states. All the elements placed inside a <State> will appear as the representation of that button state. The button tag can include a type attribute that can be set to "push" or "menu", specifying how the button behaves:
If the button states specify the looks, the events specify what to do when a button changes state - two types of actions can be specified: scripting to execute or audio to play. The following events are possible, depending on the mouse interaction with the button:
Buttons are outputted to PDF by showing only its "up" state. Associated audio and script are not exported.
The <Video> tag can integrate video from the following formats:
The next example displays a video loaded from a QuickTime movie, at a 200x160 size, in 12 frames per second:
Please have the following characteristics in mind when encoding videos, most of these are limitations derived from running on a web server environment:
In general, encoding time and final file size can be improved by the following two factors:
Video (except loaded from FLV format) is exported to PDF as individual images, one per frame/page.
The <Audio> tag can integrate audio from the following formats:
The next example plays an audio block encoded from a WAV file, with an high ADPCM encoding quality:
Please have the following characteristics or limitations in mind when encoding audio, most of them derived from running on a web server environment:
With the <Script> tag, Turbine supports ECMA-262 Script, also known as Action Script or JavaScript. The full ECMA Script specification is available at:
Although the above standard specification covers the whole ECMA-262, we suggest instead using the Action Script reference included with the Macromedia Flash authoring tool help, which is also available online at the Macromedia.com website:
The subset of this standard supported by the Macromedia Flash MX authoring tool is also supported by Turbine with the following characteristics:
On the next example, Action Script variables are set by the script tag:
All the usual object-oriented techniques are supported - on the next example, an onEnterFrame handler is set to _root:
Script blocks can interact with Turbine elements, by using the instance attribute - on the next example, the coordinates of an <Image> are manipulated from a script object, by setting them to the current mouse position:
Scripting can also be loaded from an external file or HTTP location by using the src attribute:
Scripts are not exported to PDF. When used with the Turbine Window (by setting {Media.Debug} to Yes or through the <Media> tag), debug messages can be issued from a script block for debugging purposes. This is done by calling the turbineDebug(msg) function, which is made available when the Turbine Window is included on the generated media. On the next example messages are logged by calling this function:
What happens when the pos attribute of a visual object is not specified - where is it placed? The answer depends on the current AutoLayout settings defined by the <AutoLayout> tag, or by the default {System.AutoLayout} variable. Depending on the AutoLayout type, the behavior is:
When using Vertical or Horizontal AutoLayout types, we can align the elements column or elements row, with the align attribute, using the usual left, right or center alignments.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
