Creating your own theme templates

From Autopano

Jump to: navigation, search

Contents


INTRODUCTION

This tutorial shows how to create different templates starting from a given tour) that will allow new tours to be generated with Panotour Pro that retain the same properties and which do not require XML files to be reworked, or the modification of graphical resources, following the generation of a tour.

This tutorial is designed for users who wish to go beyond the behavioral templates and graphical templates offered by Panotour Pro, and who do not want to have to edit XML files after generating a tour in Panotour Pro.


PREREQUISITES

It is preferable to read the tutorial concerning the creation of a grapical template before reading this.

A basic knowledge of the krpano description syntax is necessary in order to understand the different points contained in this tutorial.


DESCRIPTION OF THE TOUR


The virtual tour on which this tutorial is based can be viewed here.
This tour was created with Panotour Pro. The XML files were then modified to add customized elements.


This tour contains several elements that were subject to "modeling":

  • A button bar with particular positioning.



  • A specific progress bar.




  • Use of external plugins:
    • The DoubleClick plugin (developed by Aldo Hoeben) used to enter/exit full screen mode.
    • The Textfield plugin (developed by Klaus Reinfeld) used to display button bar “tool tips”.


  • Actions allowing changing of cursors and the control mode of the tour.


DESCRIPTION OF TEMPLATES FOLDERS

In this tutorial we shall be required to go into the Panotour Pro template folder.
To find this folder in your system, open Panotour Pro and select the menu entitled Edit/Open the template folder.

Image:Tutorial_ptp_theme_ptp_en_menu.png


A system window will open showing the contents of the Templates folder:

Image:Tutorial_ptp_template_templates_directory.png


html folder

This folder contains the HTML page templates offered by Panotour Pro in the Tour Build tab.
If an HTML template needs additional files, these files must be placed in a sub-folder of the same name as the HTML file.
The contents of this sub-folder will be copied to the folder where the tour is to be generated.

Image:Tutorial_ptp_template_html_directory.png


menu folder

This folder contains the description files of the functionalities displayed during the tour.
By default, this contains 30 files describing the different button bars offered by Panotour Pro.

Image:Tutorial_ptp_template_menu_directory.png


progress folder

This folder contains the XML descriptions for the progress bars offered in Panotour Pro in the field entitled Progress bar.

Image:Tutorial_ptp_template_progress_directory.png


textstyle folder

This folder contains the descriptions of the text effects offered by Panotour Pro in the Text, effect option.

Image:Tutorial_ptp_template_textstyle_directory.png


themes folder

This folder contains the XML files describing the themes offered by Panotour Pro.
Each file contains a description of the graphical resources of the theme.

Image:Tutorial_ptp_template_themes_directory.png


transition folder

This folder contains descriptions of each of the transitions offered by Panotour Pro for hotspots linked to a panorama.

Image:Tutorial_ptp_template_transition_directory.png

CREATION OF A MENU TEMPLATE

Here we want to create a menu template and a theme template based on an existing tour. The easiest way is to first create the menu template based on the code of the tour.
The description code for the tour can be found here: index.xml


Here is the section of code (to be found between the 2 KrPano code of my own buttons commentaries) added by Panotour Pro after generation:

<plugin name="dblclick" url="dblclick.swf" alturl="dblclick.js" keep="true" ondblclick="switch(fullscreen)"/>
<events onenterfullscreen="changefullscreenmenu();" onexitfullscreen="changefullscreenmenu();"/>
<action name="changefullscreenmenu">
if (fullscreen, set(plugin[fullscreenmenu].onhover, setmenutext(rightmenutxt, Exit Fullscreen);); , set(plugin[fullscreenmenu].onhover, setmenutext(rightmenutxt, Enter Fullscreen);); );
</action>
<events onxmlcomplete="changerotationmenu();"/>
<action name="changerotationmenu">
if (autorotate.enabled, set(plugin[rotationmenu].onhover, setmenutext(rightmenutxt, Stop Rotation);); , set(plugin[rotationmenu].onhover, setmenutext(rightmenutxt, Start Rotation);); );
</action>
<style name="menutxtstyle" url="textfield.swf" devices="flash" selectable="false" keep="true" height="30" background="false" textglow="4" textglowcolor="0x000000" x="0" y="55"/>
<plugin name="leftmenutxt" style="menutxtstyle" align="leftbottom" edge="leftbottom" css="p{color:#ff6600; font-family:Arial; font-size:20; margin-left:5; margin-right:5; text-align:left; }"/>
<plugin name="rightmenutxt" style="menutxtstyle" align="rightbottom" edge="rightbottom" css="p{color:#ff6600; font-family:Arial; font-size:20; margin-left:5; margin-right:5; text-align:right; }"/>
<action name="setmenutext">set(plugin[%1].html, [p] %2 [/p]);</action>
<action name="resetmenutext">set(plugin[%1].html, '');</action>
<plugin name="menudata" keep="true" mousetype="moveto" playsounds="true"/>
<plugin name="banner" url="banner.png" align="bottom" width="100%" keep="true" handcursor="false" capture="false" enabled="false" zorder="0"/>
<style name="leftstyle" keep="true" url="buttons.png" align="leftbottom" y="0" onout="resetmenutext(leftmenutxt);" onhover="setmenutext(leftmenutxt , get(tip));" zorder="1"/>
<style name="rightstyle" keep="true" url="buttons.png" align="rightbottom" y="0" onout="resetmenutext(rightmenutxt);" onhover="setmenutext(rightmenutxt, get(tip));" zorder="1"/>
<plugin name="zoomin" style="leftstyle" crop=" 0|0|44|44" onovercrop=" 0|44|44|44" ondowncrop=" 0|88|44|44" x="5" onup="set(fov_moveforce,0);" ondown="set(fov_moveforce,-1);" tip="Zoom In"/>
<plugin name="zoomout" style="leftstyle" crop=" 42|0|44|44" onovercrop=" 42|44|44|44" ondowncrop=" 42|88|44|44" x="45" onup="set(fov_moveforce,0);" ondown="set(fov_moveforce,+1);" tip="Zoom Out"/>
<plugin name="moveleft" style="leftstyle" crop=" 84|0|44|44" onovercrop=" 84|44|44|44" ondowncrop=" 84|88|44|44" x="85" onup="set(hlookat_moveforce,0);" ondown="set(hlookat_moveforce,-1);" tip="Move Left"/>
<plugin name="moveright" style="leftstyle" crop="126|0|44|44" onovercrop="126|44|44|44" ondowncrop="126|88|44|44" x="125" onup="set(hlookat_moveforce,0);" ondown="set(hlookat_moveforce,+1);" tip="Move Right"/>
<plugin name="moveup" style="leftstyle" crop="168|0|44|44" onovercrop="168|44|44|44" ondowncrop="168|88|44|44" x="165" onup="set(vlookat_moveforce,0);" ondown="set(vlookat_moveforce,-1);" tip="Move Up"/>
<plugin name="movedown" style="leftstyle" crop="210|0|44|44" onovercrop="210|44|44|44" ondowncrop="210|88|44|44" x="205" onup="set(vlookat_moveforce,0);" ondown="set(vlookat_moveforce,+1);" tip="Move Down"/>
<plugin name="rotationmenu" style="rightstyle" crop="255|0|44|44" onovercrop="255|44|44|44" ondowncrop="255|88|44|44" x="165" onclick="playorstoprotation();" tip="Stop Rotation"/>
<plugin name="sound" style="rightstyle" crop="298|0|44|44" onovercrop="298|44|44|44" ondowncrop="298|88|44|44" x="125" onclick="playorstopsounds();" tip="Stop Sounds"/>
<plugin name="dragmode" style="rightstyle" crop="342|0|44|44" onovercrop="342|44|44|44" ondowncrop="342|88|44|44" x="85" onclick="changemousetype();" tip="Change Navigation Mode"/>
<plugin name="showhelp" style="rightstyle" crop="386|0|44|44" onovercrop="386|44|44|44" ondowncrop="386|88|44|44" x="45" onclick="displayHelp();" tip="Help"/>
<plugin name="fullscreenmenu" style="rightstyle" crop="429|0|44|44" onovercrop="429|44|44|44" ondowncrop="429|88|44|44" x="5" onclick="switch(fullscreen);" tip="Enter Fullscreen"/>
<action name="playorstoprotation">
switch(autorotate.enabled); changerotationmenu();
</action>
<action name="playorstopsounds">
switch(plugin[menudata].playsounds); 
if (plugin[menudata].playsounds, playsoundaction(); set(plugin[sound].onhover, setmenutext(rightmenutxt, Stop Sounds);); , stopsoundaction(); set(plugin[sound].onhover, setmenutext(rightmenutxt, Play Sounds);); );
</action>
<action name="changemousetype">
if (plugin[menudata].mousetype == moveto, set(plugin[menudata].mousetype, drag2d); , set(plugin[menudata].mousetype, moveto); ); 
setMouseType(get(plugin[menudata].mousetype));
</action>
<action name="setMouseType">
set(control.mousetype, %1); if (%1 == moveto, setarrowcursors();, sethandcursors(););
</action>
<!-- Change Cursors Appearance -->
<action name="setarrowcursors">
set(cursors.url, arrowcursors.png); 
set(cursors.type , 8way); 
set(cursors.move , 0|0|20|20); 
set(cursors.drag , 0|0|20|20); 
set(cursors.arrow_l , 20|0|20|20); 
set(cursors.arrow_lu, 40|0|20|20); 
set(cursors.arrow_u , 60|0|20|20); 
set(cursors.arrow_ru, 80|0|20|20); 
set(cursors.arrow_r , 100|0|20|20); 
set(cursors.arrow_rd, 120|0|20|20); 
set(cursors.arrow_d , 140|0|20|20); 
set(cursors.arrow_ld, 160|0|20|20);
</action>
<action name="sethandcursors">
set(cursors.url, handcursors.png); set(cursors.type, 2way); set(cursors.move, 0|0|32|32); set(cursors.drag, 32|0|32|32);
</action>
<events onnewpano="newPanoIsLoadedAction"/>
<action name="newPanoIsLoadedAction">setMouseType(get(plugin[menudata].mousetype));</action>
<plugin name="helpScreen" align="center" customColor="true" keep="true" onclick="closeHelp();" url="help.png" visible="false"/>
<action name="displayHelp">
set(plugin[helpScreen].visible,true); set(plugin[showhelp].onclick,closeHelp();)
</action>
<action name="closeHelp">
set(plugin[helpScreen].visible, false); set(plugin[showhelp].onclick, displayHelp();)
</action>


Creation of description file for new menu

  • Open the templates/menu, folder and create a new file named tutorialthememenu.xml.
  • Edit this file:
    • A menu description file must have “menu” as its main tag and must contain a title that can displayed in Panotour Pro.
    • Let us begin by adding the following to the tutorialthememenu.xml file:
<menu>
    <translation>
        <caption lang="fr" text="Zoom - Navigation - Rotation - Sound - Control - Help - FullScreen"/>
        <caption lang="en" text="Zoom - Navigation - Rotation - Sound - Control - Help - FullScreen"/>
    </translation>



</menu>


Note :

  • It is possible to add as many caption lines as you wish for translations of the theme title.
  • The lang field must contain a value representing the language used (en, fr, ru, de, pt, es, etc.) in the text field.


We then insert all of the code added to the tour (as described below) before the end tag in the file.
This file can be used as it is by PTP if it is associated with a theme.
This requires, though, copying all the theme resources by hand following generation of the tour.
We shall see how to specify resources to be included in the tour.


Accuracy of resource paths

Image paths

5 images are used in the following code:

    <plugin name="banner" url="banner.png"  align="bottom" width="100%" keep="true" handcursor="false" capture="false" enabled="false" zorder="0"/>
    <style name="leftstyle"  keep="true" url="buttons.png" align="leftbottom"  y="0" onout="resetmenutext(leftmenutxt);"  onhover="setmenutext(leftmenutxt , get(tip));" zorder="1"/>
    <style name="rightstyle" keep="true" url="buttons.png" align="rightbottom" y="0" onout="resetmenutext(rightmenutxt);" onhover="setmenutext(rightmenutxt, get(tip));" zorder="1"/>
      set(cursors.url, arrowcursors.png);
      set(cursors.url, handcursors.png);
    <plugin name="helpScreen" align="center" customColor="true" keep="true" onclick="closeHelp();" url="help.png" visible="false"/>


We shall include images in the theme that we will create later on in this tutorial.
Add the$(STYLEDIR) tag in front of each image so that Panotour Pro knows that these images come from a theme and that it needs to recopy from the theme to the tour.
This tag will be replaced on startup of PTP by the image path in the tour.
Here are the modifications made:

  • banner.png
    <plugin name="banner" url="$(STYLEDIR)/banner.png"  align="bottom" width="100%" keep="true" handcursor="false" capture="false" enabled="false" zorder="0"/>
  • buttons.png
    <style name="leftstyle"  keep="true" url="$(STYLEDIR)/buttons.png" align="leftbottom"  y="0" onout="resetmenutext(leftmenutxt);"  onhover="setmenutext(leftmenutxt , get(tip));" zorder="1"/>
    <style name="rightstyle" keep="true" url="$(STYLEDIR)/buttons.png" align="rightbottom" y="0" onout="resetmenutext(rightmenutxt);" onhover="setmenutext(rightmenutxt, get(tip));" zorder="1"/>
  • arrowcursors.png
      set(cursors.url, $(STYLEDIR)/arrowcursors.png);
  • handcursors.png
      set(cursors.url, $(STYLEDIR)/handcursors.png);
  • help.png
    <plugin name="helpScreen" align="center" customColor="true" keep="true" onclick="closeHelp();" url="$(HELPSCREEN)" visible="false"/>

Special case of the help.png help screen:
This file contains text that you may wish to internationalize. In this case, the image included in your theme will exist in several versions.
In order for Panotour Pro to know which version to fetch, the image must be described in a particular way in the theme and in the menu.
Here we must replace the filename with the $(HELPSCREEN) tag.
It will be the theme and you yourself that will choose which image (from among the existing ones) will replace this tag.


Paths for external plugins

The code for the tour contains 2 external plugins represented by 3 files:

  • DoubleClick: dblclick.swf et dblclick.js
    <plugin name="dblclick" url="dblclick.swf" alturl="dblclick.js" keep="true" ondblclick="switch(fullscreen)"/>
  • TextField : textfield.swf
    <style name="menutxtstyle"  url="textfield.swf" devices="flash" selectable="false" keep="true" height="30" background="false" textglow="4" textglowcolor="0x000000" x="0" y="55"/>


There are two ways to include these plugins in the menu description:

1. One way is to include these plugins in the same theme as the images, in which case the $(STYLEDIR) tag must be used for the images.

  • DoubleClick
    <plugin name="dblclick" url="$(STYLEDIR)/dblclick.swf" alturl="$(STYLEDIR)/dblclick.js" keep="true" ondblclick="switch(fullscreen)"/>
  • TextField
    <style name="menutxtstyle"  url="$(STYLEDIR)/textfield.swf" devices="flash" selectable="false" keep="true" height="30" background="false" textglow="4" textglowcolor="0x000000" x="0" y="55"/>


2. The other way is used for reasons of maintenance (for example, if you would prefer to keep all your external plugins in the same folder on your system and not include them in the theme).
In this case, prefix the name of each plugin with the local path to where the files are stored on your hard disk. So if the plugins are in the d:/myTourPlugins/ folder, the preceding lines become:

  • DoubleClick
    <plugin name="dblclick" url="d:/myTourPlugins/dblclick.swf" alturl="d:/myTourPlugins/dblclick.js" keep="true" ondblclick="switch(fullscreen)"/>
  • TextField
    <style name="menutxtstyle"  url="d:/myTourPlugins/textfield.swf" devices="flash" selectable="false" keep="true" height="30" background="false" textglow="4" textglowcolor="0x000000" x="0" y="55"/>


Panotour Pro will replace the local path with the path for the plugin in the tour, after having copied the plugin to the tour.
For practical reasons, we have included the plugins in the theme described below (first solution).


Progress bar

There are two ways to specify a progress bar in Panotour Pro templates:

  • If your progress bar is generic enough, you may want to use it regardless of the menu selected in Panotour Pro. In this case, you will have to describe a new progress bar template in the progress sub-folder.
  • The progress bar in question is placed just above the button bar and its color is the same as for the different elements of the tour. It forms an integral part of the template that we are creating. The progress bar used in the previous tour is described in each panorama by the following line:
    <progress showload="bar(midbottom, 100%, 2, 0, 55, shaded, 0x0a0a0a, 0xff6600, 0xff6600, 0x9f9f9f, 0, 0x9f9f9f, 0)" showreloads="true" showwait=""/>


Just copy this line into the template file that we are creating so that it can be used by Panotour Pro. Panotour Pro will copy this line to each of the files that describe a panorama.


Accuracy of colors chosen in Panotour Pro

So far we have described a template for buttons, cursors, plugins etc., all the elements of which are orange.
Although the button bar that we have described can be used for different tours, this color is not necessarily the most all-purpose one.


Panotour Pro allows the user to set the color used for a theme and a menu (via the color input field).
This color will be applied to all the “colorizable” resources in the theme. We shall see later how to describe these images in a theme.


In our case, we have to color those elements that are not included in the graphical theme: the tool tips above the buttons and progress bar.
To do this, we shall replace the color orange (0xff6600) of the theme with the tag $(THEME_COLOR_RRGGBB).

  • The progress bar is then described as follows:
	<progress showwait="" showload="bar(midbottom, 100%, 2, 0, 55, shaded, 0x0a0a0a, 0x$(THEME_COLOR_RRGGBB), 0x$(THEME_COLOR_RRGGBB), 0x9f9f9f, 0, 0x9f9f9f, 0)" showreloads="true"/>
  • And the tool tips like this:
    <plugin name="leftmenutxt"  url="$(STYLEDIR)/textfield.swf" devices="flash" align="leftbottom"  x="0" y="55" edge="leftbottom"  selectable="false" keep="true" height="30" background="false" css="p{color:#$(THEME_COLOR_RRGGBB); font-family:Arial; font-size:20; margin-left:5; margin-right:5; text-align:left; }" textglow="4" textglowcolor="0x000000" />
    <plugin name="rightmenutxt" url="$(STYLEDIR)/textfield.swf" devices="flash" align="rightbottom" x="0" y="55" edge="rightbottom" selectable="false" keep="true" height="30" background="false" css="p{color:#$(THEME_COLOR_RRGGBB); font-family:Arial; font-size:20; margin-left:5; margin-right:5; text-align:right; }" textglow="4" textglowcolor="0x000000" />


CREATION OF A THEME TEMPLATE

The tutorial entitled Use your own graphical theme describes how to create ones own graphical theme using an existing button bar template.
The theme that we are to create here is much simpler as it uses very few graphical resources and is only compatible with the menu template that we have created.


In the themes sub-folder, we are going to create the tutorialtheme.xml file containing the description of the theme.
In the themes/graphics sub-folder, we will create the TutorialTheme folder that will contain the graphical resources of the theme.
We then copy all of the graphical resources used by the theme into the resources folder.

Image:Tutorial ptp template resources directory.png


In the theme description file, we only have a few things to find out:

  • General information (name of theme, resources folder, default color):
	<PTTheme name="TutorialTheme" directory="./graphics/TutorialTheme" customColor="true" defaultcolor="#ff6600">
		<translation>
			<caption lang="fr" text="Tutorial Theme" tip="Tutorial Theme"/>
			<caption lang="en" text="Tutorial Theme" tip="Tutorial Theme"/>
		</translation>


  • The menu template compatible with this theme (template XMLfile, preview image to be used in Panotour Pro, “colorizable” elements and the help screen):

Note: We do not want to color all the resources of the theme so we must provide a list of colorizable elements.
The colorizable elements of the menu are the names of the “plugins”, “styles” and “actions” containing the URL of a colorizable resource.

	<menus>
		<menu file="tutorialthememenu.xml" preview="buttons.png" colorize="leftstyle;rightstyle;setarrowcursors;helpScreen">
			<helpscreens>
				<helpscreen file="help_en.png" caption="Help" lang="en"/>
			</helpscreens>
		</menu>
	</menus>


  • The hotspots that the theme contains (we have two: one simple icon and an animated sequence):
	<hotspottypes>
		<hotspottype default="map" nbfile="1" file="map_spot_tuto.png" colorizeable="true">
			<translation>
				<caption lang="fr" text="Tutorial map spot"/>
				<caption lang="en" text="Tutorial map spot"/>
			</translation>
		</hotspottype>
		<hotspottype default="pano" nbfile="1" file="hotspots/hotspot_tuto.png" nbframes="10" colorizeable="true" framewidth="32" frameheight="32">
			<translation>
				<caption lang="fr" text="Tutorial Animated Sequence"/>
				<caption lang="en" text="Tutorial Animated Sequence"/>
			</translation>
		</hotspottype>
	</hotspottypes>


CONCLUSION

The templates that we have created can now be used in Panotour Pro to generate tours like this one not requiring any work after generation.


To reuse these templates:

  • Download a zip archive containing the templates here: KolorTutorialTemplates.zip.
  • Open Panotour Pro.
  • Select the “Edit/Open template folder” menu.
  • Copy the archive to this folder.
  • Unzip the archive.
  • Restart Panotour Pro.









Technical Support / Panotour Pro Documentation

Personal tools