Use your own graphical theme
This documentation is for version 1.8. For the latest and up to date versions SEE HERE.
This tutorial is intended for Panotour Pro users wishing to use their own icons rather than those offered by the four themes supplied with Panotour Pro.
It will explain how to create a graphical theme that can be integrated into Panotour Pro.
- You need to have mastered the tools used in the creation and modification of graphical icons (Illustrator, Photoshop, etc.).
- You have to be able to modify XML files.
Although no knowledge of XML syntax is required, you need to have no fear of editing such files.
In this tutorial we will make frequent use of the term “menus” in reference to the Control Bars offered by Panotour Pro.
CREATION OF A GRAPHICAL THEME
- When Panotour Pro is launched it will overwrite all templates with read-only access rights.
- In order to ensure consistency between the version of Panotour Pro and the templates we supply.
Copying an Existing Theme
Using the Edit/Open template folder/... menu, open the folder containing the descriptions of the graphical themes: themes/
By default, this folder contains four XML (2D.xml, 3DGlow.xml, basic.xml and sketch.xml), and a sub-folder named graphics.
Each XML file contains the description of the theme associated with it. Panotour Pro loads these files so that it can offer menus, default parameters and the hotspots for the themes.
- Copy the file named 2D.xml and rename it as newTheme.xml.
- Edit the newTheme.xml file using a text editor. This file begins with the following lines:
- The first 11 lines (in blue) are commentaries explaining the parameters of the useful lines that follow. You can delete them or keep them in the new file.
- For the copy of the theme to be visible in Panotour Pro, you must give it a name other than 2D.
- Change the values of the name, text and tip fields:
- Panotour Pro currently ignores the values in the tip fields.
- The name field is used to distinguish this theme from others.
- The text field is used to display the theme in the list of Themes in the software interface.
- If you wish to translate the name of your new theme into a language other than French or English, you can add a caption line.
Here are the first few lines of the file after these changes have been made:
If you restart Panotour Pro at this stage, you will see the new theme appear in the Themes list found under the Project Properties/Appearance tab.
It is, though, still using the graphical resources of the 2D theme, as we have not yet modified the directory field in the XML description file.
This field shows the path where Panotour can find the graphical resources of the theme (in the case of the 2D theme, these resources are in the graphics/2DPURE sub-folder).
- Open the graphics folder and make a duplicate of the 2DPURE folder, renaming this copy NewTheme.
- To make this new resources folder usable, edit once more the newTheme.xml file replacing the path in the directory field.
ThenewTheme.xml file now starts as follows
If you now restart Panotour Pro, this new theme will use its own graphical resources (for the moment the same as the 2D theme).
Modifying graphical resources
This theme is now operable in Panotour Pro and you can now replace the graphical elements of the theme that we have copied with your own.
Open the graphics/NewTheme folder. This folder contains 14 representations of buttons in the png format, help screens and 2 sub-folders: hotspots and menuPreviews:
The buttons used in the 2D theme that we have copied are files containing 2 representations, 2 different button states: "normal" state and "onover" state.
Your buttons need to be positioned as are the 2D theme buttons in order that they can be used by the menu templates supplied by Panotour Pro:
- One above the other, centered on the same vertical axis.
- Each button must fit in a square. The resulting file, then, is a rectangle with a ration of 1:2.
- The 2D theme icons are 65 pixels wide and 130 pixels high. This width of 65 pixels is recognized by Panotour Pro by default.
- If you wish to create or use icons of a different width, you need to modify the newTheme.xml file by adding the iconwidth parameter.
So if you use icons 32 pixels wide, the general description of the theme line in the newTheme.xml file becomes:
Be aware, though, that the final size of the buttons in the tour will be 40 pixels. This is the display size that is defined in each of the menu templates supplied with Panotour Pro.
It is advisable, therefore, to not create buttons that are too small as this risks a degradation in their quality.
Replace the 14 buttons that were copied with your own buttons, taking care to keep the same file names.
The names of files representing buttons must not be modified as this is how they are referenced in the menu templates.
You have probably noticed when using Panotour Pro that the themes we supply are "colorizable".
This modification of hue is totally independent of the original color of the buttons, which is retained in source files.
- If you wish your theme to be "colorizable":
Your icons must contain at least one color other than black and white (the black and white will be retained as such and the color will be replaced with the color chosen in Panotour Pro).
The color you wish to be applied by default must be defined in the defaultcolor field, in the general description line of your theme.
If you wish the default color to be red, for example, this line becomes:
- If you do not wish your theme to be colorizable:
Change the value of the property to customColor = "false" and remove the defaultcolor field.
- You may also wish to colorize certain buttons and to not apply colorization to others:
In this case, the customColor value must be "true", and we shall see how to specify the buttons to be colorized in the section concerning the menus that can be used with your theme.
You now have a theme with your own buttons that can be used in Panotour Pro. Although Panotour Pro does not, for the moment, display previews of the buttons in the software, the buttons for the tour generated are the correct ones.
Modifying the menu previews
For Panotour Pro to be able to correctly display a preview of the different menus offered for a theme, you must create these previews.
Open the menuPreviews folder which is to be found below the folder containing the buttons that you just have modified.
This menuPreviews folder contains 30 preview files corresponding to the 30 menus offered by Panotour Pro.
If you wish to have a correct preview for each of the 30 menus, you need to modify the 30 images contained in this folder.
That said, however, you do not have to proceed with this step to ensure correct functioning of your theme when the tour is viewed; it is merely to provide ease of use IN Panotour Pro.
You are also not required to comply with any naming syntax for the preview files as the link between them and the corresponding menus is made in the theme description file. We shall see how a little later. Given the number of files, however, we advise you to retain the same names as the files supplied by us.
Modifying help screens
The help screens used during tours are defined in the same folder as the buttons.
Panotour Pro offers 3 help images localized in a given language: One in French, one in English and the third in German.
The help image is unique and does not adapt to the menu selected in Panotour Pro.
You can make as many help images as you wish; we shall see later on how to associate them with a menu.
Hotspots are found in the hotspots folder.
Although the 2D theme offers only 9 hotspots in Panotour Pro, the folder we have just copied contains 41 files.
This is because in the 2D theme, the hotspot sequences are created from multiple files. Each file represents one state of the hotspot in the sequence.
Note: For the Basic theme, we took the option of describing the sequential hotspots using a single file. In this case, the files represent the different states of the hotspot in a vertical fashion.
We shall see later on how to describe these 2 types of sequence in the newTheme.xml theme description file.
- The hotspots you create can be image files or flash files.
- Animated GIFs do not function correctly in Flash tours. Although they do function in tours on the iPad, we do not recommend this as the graphical rendering is less good than when using a sequence of images.
You are not required to comply with any naming syntax for files representing hotspots, unless you are describing a sequence of hotspots using multiple files.
In this case, the files representing the sequence must be numbered from 1 to n, where n represents the number of files used in a complete sequence.
Description of new graphical resources
As you saw earlier, there is no requirement to describe buttons in the newTheme.xml description file in order to use them in a tour.
This is not the case for all graphical resources however.
This section explains how to describe different theme resources in the newTheme.xml file.
Menus that can be used with this theme
The newTheme.xml file contains a list of the 30 menus with which this new theme is compatible.
If you only use some of the 30 menus offered, you can remove the others from the theme description. These menus will not then appear in the list of menu templates in Panotour Pro.
The menus that are compatible with the theme are described in two different ways, depending on whether or not they contain the button allowing the help screen to be displayed.
Here is an example of a menu description without a help screen. It fits on one line:
- The file attribute indicates the menu description file with which this theme is compatible.
- The preview attribute indicates the preview image path of the menu. If you have renamed the preview files, you need to change the value of this attribute.
- The colorize attribute indicates the list of colorizable buttons in the menu.
- If all the buttons contained in your theme are colorizable, leave "all" as the value for this attribute.
- If only certain buttons are colorizable, this field needs to show a list of the names of plugins as defined in the file indicated by the file attribute, separated by semi-colons ";".
For example, if only the navigation buttons are colorizable in the previous menu, the description line for the compatible menu becomes:
Here is an example of the description for a menu containing a help button:
The only difference with the previous case is that the menu description contains the list of help images that can be used for this menu.
- The file attribute indicates the name of the image file that will be used as the help screen. It is this filename that will be displayed in the Help Screen list that appears with the Control Bar options in Panotour Pro.
- The caption attribute is not currently used by Panotour Pro, but it should be the name of the help screen as displayed in Panotour Pro.
- The lang attribute indicates the language in which this help screen is written. The help screen which will be selected by default in Panotour Pro is the one which is in the same language as Panotour Pro, if such exists.
Descriptions of hotspots
The newTheme.xml file contains 9 descriptions of hotspots.
Here is the description of a simple hotspot which uses just a single image:
- The nbfile attribute indicates that the hotspot is described by one single file
- The file attribute indicates the path to the hotspot file.
- The caption lines give the different names for the hotspot depending on the language being used in Panotour Pro.
- The colorizable attribute indicates whether the hotspot is colorizable or not. Set this attribute to false in the case of a flash hotspot.
To indicate that this hotspot is the default hotspot to be offered by Panotour Pro for a given panorama, it is necessary to add the default attribute and give it the value "pano".
To indicate that this hotspot is the hotspot to be offered by default by Panotour Pro in a map or a PanotourMaps plan, it is necesasry to add the default attribute and give it the value "map".
A sequential hotspot that stores each state in a distinct file is described in the following manner:
- The nbfile attribute indicates that this sequential hotspot is described by 10 files.
- The value of the file attribute aways indicates the path to the hotspot files, but in a generic way. The number contained in the filename indicating the place of this hotspot state in the sequence is replaced by %d.
- The refreshPeriod attribute indicates the time period between each hotspot state change.
A sequential hotspot for which all the states are defined in a single file is described in the following manner:
- The nbframes attribute indicates the number of hotspot states represented by the files.
- The framewidth attribute indicates the width of the icon representing a hotspot state.
- The frameheight attribute indicates the height of the icon representing a hotspot state.
If you have followed all the steps, you are now ready to create your own graphical themes based on the control bars offered by Panotour Pro.
In another tutorial, we shall see how to create your own menu and interaction templates in order to obtain this type of tour generated by Panotour Pro.