Panotour - Advanced - Creating a custom control bar
Contents
Introduction
This tutorial is intended for Panotour Pro users wishing to use their own icons in a control bar rather than the default control bars offered by the software.
This tutorial will be basing itself on a pre-existing control bar, explaining each of the components of a control bar and recreating the icons for the buttons.
Requirements and notes
- You need Panotour Pro to install and use customised plugins.
- You need to have mastered the tools used in the creation and modification of graphical icons (Illustrator, Photoshop, GIMP, etc.).
- You have to be able to modify XML files. Although no knowledge of XML syntax is required for this tutorial, you need to have no fear of editing such files. The use of editors such as Notepad ++or Sublimetext is recommended to view XML files clearly.
The control bar used as an example in this tutorial is available to download on our Extra Plugins page.
What's a control bar made of?
Like all plugins to be used in Panotour Pro, a control bar plugin is comprised of several files:
- Plug_info.xml - This XML file describes the plugin and its customization interface that will be displayed in Panotour. It also describes many other things like dependencies, or any assets you want to embed.
- PluginName.tmpl - This file is a template file, you can name it as you like, it will be called by the plug_info.xml. In it you will find Krpano script, actions and custom XML that will be used in the tour.
- Prefer original names for each plugin so don't hesitate to be wordy. For example: mysupermegapluginthatdoesthis.tmpl
- Images for each icon used by the control bar
- Ptpreview folder - This folder contains the preview image(s) shown in Panotour Pro when browsing the plugins library.
- Skins folder - This folder is not present with every control bar template, but all of Panotour's default plugins are coded to react and use this skin folder if added.
For more information about the composition of a plugin, see How to create a Panotour plugin.
Note:
Some extra files as well as the control bar icons may be in the template folder, some of the control bars come with extra graphics (background image, hotspots) which are not currently used and are left for future use. You can leave them be as they will not affect your control bar.
Customising your own control bar
Step One: Copying a template
- Open Panotour Pro.
- Go to Edit > Open Template System Directory. This will open a file explorer containing all the plugins and content that is available by default in Panotour Pro.
- Open the plugins folder, and select a control bar to copy. In this tutorial we will be using the iControl bar as a base, so copy (Ctrl+C) that folder.
Step Two: Pasting and renaming the template
- Back to in Panotour Pro
- Go to Edit > Open User Directory. This will open a file explorer containing all the custom plugins and content that you have added to Panotour Pro.
- Open the plugins folder, paste (Ctrl+V) your copied template plugin, and rename it. I've called my new control bar CirclesControlBar.
Step Three: Using your own graphics
First we'll have to analyse how the graphics are used.
Each image contains three icons, representing three different states:
normal
hover
on click.
You'll need to create an icon for each state.
This is where your knowledge of creating icon comes in we won't be explaining how to do that in detail. Edit each file, replacing the three icons with your own and save over the file (you must keep the same name for the control bar to recognize and use the icon).
Here I have replaced all my icons and created a control bar of circular icons, using free icons from iconfinder.com (click on the image to zoom in, two of the states are white):
normal
hover
on click.
And my finished bar with all the icons looks like this:
In the folder
In a tour (with all the buttons activated)
Notes:
Creating and replacing the graphics of a control bar is what takes the longest in this tutorial.
If you want your control bar to be colorizable in Panotour, then make your icons all the same one color (prefer blunt bright colors like blue or red for an easier integration).
White or black areas will remain that color no matter the color change.
Now that we've replaced all the icons, the next step is to edit the plug_info.xml.
Step Four: Editing the xml
You have to edit the plug_info.xml so that your plugin can be opened in Panotour, it's only a few simple edits though.
Open the file in a text editor.
ID and Name
You have to change the plugin ID and name (description is optional) so that your control bar can be opened and used in Panotour Pro. The ID must be absolutely unique, so be wordy if needed.
- The first line of the plug_info.xml will be:
<plugin id="controlBar_i" category="tr:Control Bar" name="tr:iControl Bar" description="tr:Allows your visitor to browse your tour and interact with widgets" version="2.0" isGraphical="true" multipleInstance="true">- So, for my Circles Control Bar, after edits it becomes:
<plugin id="CirclesControlBar" category="tr:Control Bar" name="tr:Circles Control Bar" description="tr:Allows your visitor to browse your tour and interact with widgets" version="2.0" isGraphical="true" multipleInstance="true">
Color
Next, you will have to edit the default color of your icons, so that when the color is changed in Panotour, it changes to the right color. This is optional, if you want your buttons to stay the color you've set them, see the 3rd example in this section.
The color information is located lower down in the file, after the <resources> tag.
- Example default line for the info icon:
<file url="btn_info.png" color="color" baseColor="#b7ae9e" conditionalParam="displayinfo" conditionalValues="true"/>- Change the hex color code to the color that you used for your new icons if you want the icons to be colorizable. In my case it's #00cccc:
<file url="btn_info.png" color="color" baseColor="#00cccc" conditionalParam="displayinfo" conditionalValues="true"/>- If your icons are going to stay the same color, then just remove the color information (the color and baseColor tags) . This can be useful if you want only certain buttons to keep the initial color:
<file url="btn_info.png" conditionalParam="displayinfo" conditionalValues="true"/>
Once you've done these edits, you will be able to open Panotour Pro and use your control bar in your future virtual tours.
(optional) Preview image
This is for you to change the preview image that's used in Panotour Pro.
The preview image is located in a separate folder named ptpreview.
You can replace the image with your own but certain conditions must be kept:
- The image must be named ptpreview.png
- If you want an animated preview you can input several, in that case name them ptpreview_1, ptpreview_2, etc...
- The image size must be 280x94 to be viewed optimally. Any size bigger or smaller may end up squished or stretched.
(optional) Template file editing
Below are a few tips for further customisation of your plugin, this time you will be editing the PluginName.tmpl file, or, in the case of an iControl Bar based control bar like on this page, you will edit the theme11.tmpl file.
Same as the the xml file, you need to open the .tmpl file in an editor.
- Changing the title of the template (which is used as a comment to find your plugins in the YOURTOUR_skin.xml file of your built tour
Line 3 - iControl Bar - Change it to the name of your new control bar.
- Changing the button size in the control bar:
Line 8 - {% with 40 as button_width %} - 40 represents the button size in pixels, displayed in the tour.
- Changing the spacing between buttons in the control bar:
Line 1267 - {% with 5 as button_margin %} - 5 represents the margin in pixels.
Notes:
These tips and lines correspond to the location of the information in the theme11.tmpl, this same information may be located elsewhere in the file if you are using a different template as a base.
Editing the template file can affect how and whether or not the plugin works, so be careful with your edits.
(optional) Skins folder
If you just want to create a new skin or set of graphics for your control bar instead of a new plugin for each style, then have a look at our tutorial on skins
BACK TO: Documentation / Panotour Documentation