-
Notifications
You must be signed in to change notification settings - Fork 4
2. Understanding the Glory “config.xml” File
Apart from the project.xml file which is common to OpenFL, Glory Framework is configured using the config.xml file found in /assets. The best way to understand this file is to inspect the code provided in the /examples folder. You can add/remove/modify pages and assets simply by editing the config.xml file. If you have compiled and deployed to web and are not using app mode or custom page classes there is no recompile required — just reload the page to view your changes!
A basic config file only requires the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<pages>
<controls></controls>
<page id="title" type="normal" original="" width="960" height="640">
<actor id="bg1" z="0" type="prop" x="0" y="0" width="960" height="640" src="title/title.jpg" ></actor>
</page>
</pages>
IMPORTANT: There must be one page with an id attribute of “title”. This serves as the “home” page of the framework.
Of course, you will want to have some controls to flip between pages. Here’s an example:
<button id="bOptions" action="pageSkipTo:options" z="18" x="849" y="-11" width="111" height="71" src="nav/bOptions.png"></button>
Place button tags within the <controls></controls> tags. Right now just “button” tags are available but future releases of the framework may allow for other GUI controls.
Currently there are these button actions available for buttons and actors with type of “control”:
- pageSkipTo
- pageForward
- pageBackward
- removePage
- playSound
When you use pageSkipTo, follow it with a colon and the id of the page you want to visit when the button is pressed. The example above summons the “options” page.
For controls that appear on a single page, use actors of type “control” for your navigation, as described in the Actors section below.
Pages are holders for actors, which are the graphics, etc. displayed on screen. Each page should have a unique id, and there are currently two valid values for the type attribute:
- normal
- overlay
Normal pages will obey the pageForward and pageBackward navigation and are included in the normal page ordering. Alternatively, overlay pages are intended for modal-style dialogs, and once they are dismissed the application returns you to the page you were on when you left.
When you define an overlay page, be sure to include an actor of type “control” which is able to dismiss the overlay. See this example:
<page id="options" type="overlay" original="" width="960" height="640">
<actor id="background" type="prop" z="0" x="0" y="0" width="960" height="640" src="options/actor_0000_background.png"></actor>
<actor id="limerick" type="control" action="pageSkipTo:limerickPage,removePage:options" z="5" x="135" y="366" width="198" height="185" src="options/actor_0005_limerick.png"></actor>
<actor id="close" z="6" type="control" action="removePage:options" x="860" y="40" width="50" height="50" src="nav/close.png" ></actor>
</page>
Note in the above example that it is possible and necessary to provide two actions to actors which trigger a page change. The “removePage:yourPageId” action is necessary to dismiss the overlay page which is currently displaying – just separate that command from the other commands using a comma.
It is good practise to give each actor in your application a unique id, even if actors are in separate pages. Otherwise you will likely experience errors due to duplicate view mediators.
You may have noticed that the actor tags have two valid type attributes:
- prop
- control
If the actor is not intended to be clickable, use the “prop” value to save memory. Currently actors are added in the order which they appear in the config.xml file. The z attribute is currently useless but may be used in the future.
Actors may be .png,.jpg,.gif,.svg, or even MovieClip assets from a .swf library. All actors may be referenced using a file path in the "src" attribute. The exception to this rule is MovieClip assets – these must be placed within a page that has a swflibrary attribute and contains only MovieClip assets. These page and actor nodes have special syntax; please refer to SWF to Glory Workflow for more information.
Use a sound tag within a page to make a sound available for playback:
<sound id="s_limerickPage" src="p1/limerickPCM.mp3,p1/limerickPCM.ogg,p1/limerickPCM.wav" autoPlay="false" ></sound>
Enter multiple file paths separated by commas, and OpenFL will choose the appropriate file for your platform. These paths will only be used when not in “app mode”. The “app mode” sounds still require an id attribute which will point to assets which were configured in your project.xml. Please refer to the project.xml documentation.
Sound settings currently feature an autoPlay attribute. Future releases may feature a loop attribute.
Each page has "transitionIn" and "transitionOut" functions. They default to simple 1-second fades, but these can be overridden by using the custom page class feature. By editing the "transitionOutTime" attribute on the page tag in the config.xml file, you have some control over whether the transitionIn overlaps with the transitionOut. See the provided config.xml file and custom page class file in the /examples folder to see this.