|
|
|
|
|
|
|
# Scenario
|
|
|
|
|
|
|
|
A typical tangible table application is called a **scenario**. In close analogy to movies, novels or plays, the TULIP scenario is a written outline giving details about the *actors*, in our case TULIP objects, the individual *scenes*, i.e. the various screens the objects are shown on, and last but not least the overall *plot*, i.e. the way the different objects interact with each other.
|
|
|
|
|
|
|
|
## XML Include
|
|
|
|
|
|
|
|
Its easy to imagine that XML Scenarios can become quiet extensive, and as consequence, quiet unwieldy. To handle this complexity, TULIP scenarios support XML includes, thus giving authors the possibility to cut up their scenarios in more manageable XML chunks. Including a piece of external XML code is done like follows:
|
|
|
|
|
|
|
|
> \<xi:include href="XMLToBeIncluded.xml" parse="xml"/\>
|
|
|
|
|
|
|
|
It is important to note that, XML Include only works if the root node of the including XML file defines a property named **xmlns** as follows:
|
|
|
|
|
|
|
|
> \<scenario xmlns:xi="http://www.w3.org/2001/XInclude"\>
|
|
|
|
|
|
|
|
## Scenario Tag
|
|
|
|
|
|
|
|
The **`<scenario>`** tag is the root tag of every TULIP bootstrap file. A bootstrap file must contain exactly one scenario. The `<scenario>` tag encloses a number of child tags.
|
|
|
|
<figure>
|
|
|
|
<img src="uploads/4001d821ae75878a5139570c8479874e/ScenarioSchema.png" width="66%" height="66%">
|
|
|
|
<figcaption>Fig. 1 - Scenario XML properties</figcaption>
|
|
|
|
</figure>
|
|
|
|
|
|
|
|
### About Tag
|
|
|
|
The **`<about>`** tag provides general information about the scenario itself. Provided data will usually show up in the TULIP splash-screen, shown while the application starts up. The about contains a **`<title>`** specifying the name of the application, a **`<description>`** giving a more verbose account of what the scenario is about, and last but not least a **`<version>`** tag
|
|
|
|
|
|
|
|
>\<**about**\>
|
|
|
|
>
|
|
|
|
>\<**title**\>BIMEET\</**title**\>
|
|
|
|
>
|
|
|
|
>\<**description**\>BIMEET (BIM-based EU-wide Standardized Qualification Framework
|
|
|
|
>for achieving Energy Efficiency) project aims to leverage the take-up of
|
|
|
|
>ICT and BIM through a significant upgrade of the skills and capacities of
|
|
|
|
>the EU construction workforce. BIMEET will develop skills matrices related to
|
|
|
|
>BIM and energy-efficiency. The description of skills will be given in the
|
|
|
|
>form of the European Qualifications Framework. BIMEET will also develop a
|
|
|
|
>training platform which will support registering labeled training offering
|
|
|
|
>and finding suitable BIM training in different levels of Architecture,
|
|
|
|
>Engineering and Construction (AEC) sector.\</**description**\>
|
|
|
|
>
|
|
|
|
>\<**version**\>1.0.0\</**version**\>
|
|
|
|
>
|
|
|
|
>\</**about**\>
|
|
|
|
|
|
|
|
### StageSet Tag
|
|
|
|
The optional **`<StageSet>`** tag comes in handy when the scenario uses more than one screen. Single screen scenarios usually don't require this tag. When multiple screens are required though, this tag gives authors the possibility to control how those screens will be used by TULIP. As we have seen in Figure 1, the **`<StageSet>`** includes a sequence of **`<stage>`** elements. Each **`<stage>`** element normally corresponds to one particular screen.
|
|
|
|
<figure>
|
|
|
|
<img src="uploads/1210c327fbef4c84078bdeaefc1a6351/StageSchema.png" width="75%" height="75%">
|
|
|
|
<figcaption>Fig. 2 - Details XML properties of Stage nodes</figcaption>
|
|
|
|
</figure>
|
|
|
|
|
|
|
|
The optional **`<name>`** tag allows assigning a name to the enclosing stage object. The given name has only a documentation purpose, allowing authors to more easily identify the different stages. The mandatory **`<stageId>`** in turn assigns a numeric **Id** or **Handle** to the respective stage, used throughout the scenario for referencing the stage. It is important to note that Id or Handle **0** (zero) is reserved for the stage corresponding to the tangible table itself. User defined stages should start with the next available Id. The mandatory **`<screenId>`** links this stage with an actual screen. Determining the **Ids** of the various screens widely varies from one OS to the other. To simplify identification of the different screens, TULIP logs in its log file the different screens with their respective Ids and dimensions.
|
|
|
|
|
|
|
|
`[main] INFO Stage - Screen with ID 0 detected with bounds java.awt.Rectangle[x=0,y=0,width=1920,height=1200]!`
|
|
|
|
|
|
|
|
The optional **`<fullscreen>`** and **`<transparent>`** flag allow controlling how the native OS window hosting the stage will be shown. It is important to understand that the availability and the proper working of those features strongly depend on the OS and the respective video driver themselves. Past experience has shown that especially the **`<transparent>`** feature may suffer from *aliasing* artefacts on some operating systems.
|
|
|
|
|
|
|
|
The optional **`<bounds>`** node, with its **`<x>`**, **`<y>`**, **`<width>`** and **`<height>`** fields controls the stage dimensions in pixels. If not provided, the corresponding stage window will extend over the full extend of the corresponding screen.
|
|
|
|
|
|
|
|
Last but not least, the optional **`<backgroundColour>`** allows determining the background colour of the blank stage. The background colour will default to **Black** if the property is not provided. Have a look at the section about [common colour properties](bootstrapping/common/colour) for more information about how to define a colour in TULIP scenarios.
|
|
|
|
|
|
|
|
## Macros Tag
|
|
|
|
Macros play a crucial role in object templating. In the [Getting started](Getting-started) section we briefly mentioned the concept of templating. [Templates](bootstrapping/templates) can be compared to a blueprint or a mould to produce a number of similar objects, sharing some but not all properties with their siblings. Values for the differentiating properties are generally provided by individual **template variables**, identified by the **`$`** (dollar) sign and a pair of enclosing **{}** (brackets), or more complex expressions involving multiple variables. If an expression is being used in multiple locations, it is advisable to define the expression only once in the form of a **`<macro>`** and replace each occurrence of the given expression with the corresponding macro. Macros use a notation for their placeholder similar to template variables. Macro placeholders are identified by the **`%`** (percent) sign and a pair of enclosing **{}** (brackets). The following example defines a macro named **CriterionStartAngle**.
|
|
|
|
|
|
|
|
> \<macro identifier="CriterionStartAngle"\>${CriterionIndex} * (360 / ${NumberOfCriteria})\</macro\>
|
|
|
|
|
|
|
|
The macro defines an expression using two templating variables,i.e. **${CriterionIndex}** and **${NumberOfCriteria}**. It is worth mentioning that expressions defined in macros are replaced as is, i.e. they are not pre-evaluated but are instead evaluated *in situ*. You may compare this behaviour to a Find & Replace operation taking place during runtime, replacing every occurrence of the **%{CriterionStartAngle}** placeholder with the content of the corresponding **`<macro>`** tag.
|
|
|
|
|
|
|
|
## Template Tag
|
|
|
|
[Templates](bootstrapping/templates) will be discussed in detail in a dedicated [templating](bootstrapping/templates) section, so we won't go into much detail here. Suffice it to say that templates are the actual workhorse of most scenarios implemented with TULIP. Templates are essential for dynamic scenarios, relying on data provided from external systems to populate individual objects.
|
|
|
|
|
|
|
|
## Object Tag
|
|
|
|
The **`<objects>`** tag groups all *explicit* tangible object definitions. By explicit object definitions we understand objects which are completely and unequivocally defined and can be instantiated as is. The opposite form of object definitions are those objects requiring data from external systems, which should be defined in the previously introduced [templates](/nui/tulip/-/wikis/bootstrapping/templates) section. It is important to note though, that independently from whether an object is declared in the **`templates`** or **`objects`** section, they always share the same properties. The difference resides in what you're allowed to use to get the respective values from. If defined inside the **`templates`** sections, you're allowed the use variables to provided property values, which you're not allowed to do inside **`objects`** sections. Apart from that, declaring objects in both sections is identical. Each object definition is encapsulated in its own `<object>` tag. Tangible objects are the functional software representation of the physical object manipulated by the user and will be called hereafter **Widgets**. TULIP comes with a number of predefined widgets implementing different behaviors, however, all widgets have a set of basic properties which we'd like to introduce in the [following section](/bootstrapping/objects).
|
|
|
|
<div align="right">[Objects](/bootstrapping/objects)</div> |
