Skip to content

2. Understanding the Glory “config.xml” File

Jump to bottom Edit New page
Allan Dowdeswell edited this page Oct 9, 2019 · 18 revisions

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.

Controls

Of course, you will want to have some controls to flip between pages. Here’s an example:

<actor id="bOptions" type="control" action="pageSkipTo:options" z="18" x="849" y="-11" width="111" height="71" src="nav/bOptions.png"></actor>

Simply place actor tags within the <controls></controls> tags and configure them as desired. They will persist on screen unaffected by page changes. See the actors section below for configuration options.

Currently there are these actions available for buttons and actors with type of “control”:

  • pageSkipTo
  • pageForward
  • pageBackward
  • removePage
  • playSound
  • httpLink

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.

Pages

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.

Actors

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.

Sounds

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.

Page Transitions

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.

Layout Behaviours

If your project is set to have a dynamic stage size such as shown in the website example, you will want to have your actors adjust their position and/or size appropriately. Glory uses the Advanced Layout library under the hood to help you with this. Syntax for adding layout behaviour is as follows:

<actor id="haxeLogo" type="control" action="httpLink:haxe.org/" z="20" x="0" y="100" width="200" height="200" src="title/haxe-opt.svg" layout="fillPercentWidth:0.5,maintainAspectRatio,centerX,centerY"></actor>

Note the commands contained in the layout attribute. Glory supports a subset of the options contained within the LayoutCreator class of Advanced Layout library. Simply separate the functions you want by commas, and use a colon to pass a single parameter to the function. They will be executed in order of appearance. Remember to set the position after setting the scale. Read the Advanced Layout documentation for more help. Supported commands as follows:

  • simpleX
  • simpleY
  • centerX
  • centerY
  • center
  • alignLeft
  • alignRight
  • alignTop
  • alignBottom
  • alignTopLeft
  • alignTopRight
  • alignBottomLeft
  • alignBottomRight
  • alignLeftCenter
  • alignRightCenter
  • alignTopCenter
  • alignBottomCenter
  • horizontalPercent
  • verticalPercent
  • simpleScale
  • simpleWidth
  • simpleHeight
  • rigidSimpleScale
  • rigidSimpleWidth
  • rigidSimpleHeight
  • fillWidth
  • fillHeight
  • fillPercentWidth
  • fillPercentHeight
  • rigidFillPercentWidth
  • rigidFillPercentHeight
  • maintainAspectRatio
Add a custom footer
Add a custom sidebar
Clone this wiki locally