< Back
Jump to: navigation, search

Parameters tags documentation (plug info.xml)

Intro

This section describes all the available type of parameters and all their attributes.

For each kind of parameter, a different widget will be used in Panotour to display its value and to retrieve the values the user set.

The better you choose the parameter kind, the easier it will be to customize your plugin.

You can use only string parameters in your plugin, but it will be more difficult for a user to understand and set the parameter.



Common attributes to all different parameters

id : ID of the parameter. This ID should be unique inside the plugin. It will be used to identify the parameter in the template.

name : Name of the parameter. It will be used as a label or a title for the widget used in PTP to set the parameter.

description : Description of the parameter. It will be used as a tooltip over the parameter widget.

conditionalParam : ID of another plugin parameter which values are checked to enable or not this parameter. This attribute has to be used with conditionalValues one.

conditionalValues : Values of the conditionalParam parameters for which the parameter if available. This attribute can be a single value (true, or false for a bool parameter for example), or a comma separated list (case of a select parameter)



Data input tags

bool

description Boolean parameter : true/false
parameters 
<bool id="startActivated" name="tr:Start activated" description="tr:Activate the plugin when the tour starts" default="true" />

id : ID of the parameter

name : Parameter label

description : Description of the parameter

default : Default value : true ou false

usage 
{% if plugin.startActivated.value %}
  The plugin starts activated
{% else %}
  The plugin starts inactivated
{% endif %}


color

description Choice of a color and an alpha value
parameters 
   <color id="bgcolor" name="tr:Normal border" default="#ffffff" needalpha="true" defaultalpha="0.2" source="customColor" allowDynamicSource="false"/>

id : ID of the color

name : Parameter label

default : Default #rrggbb value of the color

needalpha : If true, indicates that the alpha value should be entered in Panotour

defaultalpha : Default value of alpha. Between 0 and 1. Not taken into account if needalpha is set to false.

source : Source of the color. It can have the following values :

  • customColor no source, the color is a custom one defined by default value
  • currentProjectForeground foreground of the current project
  • currentProjectBackground background of the current project
  • currentGroupBackground background of the current group, available only if allowDynamicSource is set to true

allowDynamicSource : If true, the user will be able to select a "dynamic" color source, for example the "current group color". If false only "static" meta colors can be selected.


usage In the template file : 
{{plugin.bgcolor.colorRRGGBB}}
{{plugin.bgcolor.alpha}}

plugin.bgcolor.colorRRGGBB The RRGGBB value of the color, without any "0x" or "#" at the begginning

plugin.bgcolor.alpha The alpha value of the color

plugin.bgcolor.lighterRRGGBB The RRGGBB value of a lighter color, without any "0x" or "#" at the begginning

plugin.bgcolor.darkerRRGGBB The RRGGBB value of a darker color, without any "0x" or "#" at the begginning

plugin.bgcolor.sourceStr The source of the color.

  • projectBackground ->colorRRGGBB contains the project background color
  • projectForeground ->colorRRGGBB contains the project foreground color
  • customColor ->colorRRGGBB contains a custom color
  • currentGroupBackground the only value to check. In this case, you need to get the current group background color


In the plug_info.xml file :

Describe the colorizeable resources by indicating wich color paramater should be used to colorize them. A resource file cannot be colorized by a "dynamic color". So color parameters with allowDynamicSource set to true cannot be used there. 

  <file url="myressourcefile.png" color="bgcolor" basecolor="#462c72"/>


datasource

description Choose between the different data of the project the ones that will be the source of the plugin.
parameters 
  <datasource   id="source" name="tr:Display"  default="allpanoramas" availablevalues="allpanoramas,allgroups,currentgroup,allpanoramasandgroups" />

id : ID of the parameter

name : Parameter label

default : Default source. Its value should be one of the availablevalues

availablevalues : Available sources separated by a comma

  • allpanoramas All the panoramas of the tour
  • allgroups All the groups of the tour
  • allpanoramasandgroups All panoramas and all tours
  • currentpanorama Current panorama
  • currentgroup Current group
  • currentproject Current project


If you want to customize the some labels of the items displayed in the selection widget, you can specify the new labels like this 

  <datasource   id="source" name="tr:Display"  default="allpanoramas" availablevalues="allpanoramas,allgroups,currentgroup,allpanoramasandgroups">
    <item value="allgroups" name="tr:Stuff from all the groups of the tour"/>
  </datasource>
usage 
{% ifequal plugin.source.mode "currentproject" %}
<!-- ********************* -->
<!-- Current Project Title -->
<!-- ********************* -->
{% endifequal %}
{% ifequal plugin.source.mode "currentpanorama" %}
<!-- ********************** -->
<!-- Current Panorama Title -->
<!-- ********************** -->
{% endifequal %}
{% ifequal plugin.source.mode "currentgroup" %}
<!-- ******************* -->
<!-- Current Group Title -->
<!-- ******************* -->
{% endifequal %}


dimension

description Gets a dimension in pixels or percentage
parameters 
  <dimension id="width"  name="tr:Width" default="0" maximum="9999" availableUnits="pixel,percent" currentunit="pixel"/>

id : ID of the parameter

name : Parameter label

default : Default value

minimum : Minimum value of dimension

maximum : Maximum value of dimension

availableUnits : Available units for the dimension separated by a comma

  • pixel
  • percent

currentunit : Default unit

usage 
  width="{{plugin.width.value}}{% ifequal plugin.width.unit "percent" %}%{% endifequal %}"


filechooser

description Allow to select a file on the local system.

The selected local file will be copied in the tour.

parameters 
  <filechooser id="file" name="tr:File" default="" filters="images,flash" allowremote="true"/>

id : ID of the parameter

name : Parameter label

default : Default file value

filters : File type filters separated by a comma. If not set, every kind of files can be selected.

  • images
  • flash
  • videos
  • pdf

allowremote : If set to true the the user will be allowed to enter an URL instead of a local file. In this case the selected file will not be copied in the tour.

usage 
{% if plugin.file.isRemote %}
         url="{{plugin.file.value}}" 
{% else %}
         url="%FIRSTXML%/{{pluginDirectory}}/{{plugin.file.fileName}}" 
{% endif %}

plugin.file.isRemote True if the selected file is an URL

plugin.file.fileName Name of the copied file in the tour

plugin.file.value Real path selected by the user in Panotour


font

description Choose a font type, a font size and a font style (bold, italic)
parameters 
  <font  id="font"  name="tr:Font"  default="Arial" size="16" style="bold,italic" />

id : ID of the parameter

name : Parameter label

default : Default family name of the font

size : Default size of the font

style : Default styles of the font : normal, bold, italic

usage 
              font-family:{{plugin.font.family}};
{% if plugin.font.italic %}
              font-style:italic;
{% endif %}
{% if plugin.font.bold %}
              font-weight:bold;
{% endif %}
              font-size:{{plugin.font.size}}px;

plugin.font.family Font family

plugin.font.bold true if the selected font is bold

plugin.font.italic true if the selected font is italic

plugin.font.underline true if the selected font is underlined

plugin.font.strikeout true if the selected font is strikedout

plugin.font.size Size of the font


number

description Allows the user to select a number
parameters 
  <number id="numberofdots" name="tr:Number" minimum="1" maximum="10" suffix="tr:dots" />

id : ID of the parameter

name : label of the parameter

default : Default value of the number

minimum : Minimum allowed value

maximum : Maximum allowed value

suffix : String placed inside the number widget to indicate what kind of object the number parameter is relative to

usage 
   {{plugin.numberofdots.value}} were selected


position

description Set the position of the plugin.
parameters 
  <position id="position"
            name="tr:Position"
            availablevalues="topleft,topright,bottomleft,bottomright,bottom,top,left,right"
            default="bottom"
            x="0" y="10"
            needorientation="true" 
            defaultorientation="horizontal"/>

id : ID of the parameter

name : Parameter label

availablevalues : Places where the plugin can be set (separate the available positions by a comma) : topleft , topright , bottomleft , bottomright , bottom , top , left , right, center

needorientation : If set to true, the widget used in PTP will also allow the user to select an orientation

defaultorientation : Default orientation, needorientation has to be set to true. Possible values : horizontal, vertical

x : Default value of the horizontal offset

x_units : Possible units for the horizontal offset : pixel, percent

x_unit : Default unit of the horizontal offset. If not set : pixel

y : Default value of the vertical offset

y_units : Possible units for the vertical offset : pixel, percent

y_unit : Default unit of the vertical offset. If not set : pixel

usage 
align="{{plugin.position.positionString}}"
x="{{plugin.position.x}}{% ifequal plugin.position.xUnit "percent" %}%{% endifequal %}"
y="{{plugin.position.y}}{% ifequal plugin.position.yUnit "percent" %}%{% endifequal %}"
{% ifequal plugin.position.orientationString "vertical" %}
  <!-- Vertical plugin -->
{% else %}
  <!-- Horizontal plugin -->
{% endifequal %}

plugin.position.positionString : Selected position : The selected value is one of the availables values set in the parameters description

plugin.position.orientationString : Selected orientation

plugin.position.x : Horizontal offset

plugin.position.xUnit : Unit of the horizontal offset

plugin.position.y : Vertical offset

plugin.position.yUnit : Unit of the vertical offset

plugin.position.alignedOnLeft : True if the plugin is aligned on left (ie if positionString is equals to topleft, left or bottomleft)

plugin.position.alignedOnRight : True if the plugin is aligned on right (ie if positionString is equals to topright, right or bottomright)

plugin.position.alignedOnTop : True if the plugin is aligned on top (topleft, top ou topright)

plugin.position.alignedOnBottom : True if the plugin is aligned on bottom (bottomleft, bottom ou bottomright)


select

description Permet de choisir une valeur parmi n
parameters 
<select id="force" name="tr:Kind of rain fall" default="normal">
  <item value="normal" name="tr:Normal" />
  <item value="heavy"  name="tr:Heavy" />
</select>

id : ID of the parameter

name : Parameter label

default : ' ID/value of the default selected item. It should be one of the values described in the "item" subnodes

item : Element describing a possible value

value : ID/value of theitem

name : Label of the item

usage 
{% ifequal plugin.force.value "heavy" %}
{% else %}
{% endifequal %}

plugin.force.value : ID/value of the item selected by the user


string

description Displays a textfield allowing the user to enter a string
parameters 
  <string id="identity" name="Identity" default="John Doe" />

id : ID of the parameter

name : Parameter label

default : Default value

usage

Direct access to the entered message : 

 {{plugin.identity.value}}

The entered value is added to the "messages" file of the tour. So it can be translated in different languages. To access to the current version of the value according to the current language you have to use getmessage action, like this : 

getmessage(mytxtvar,  {{plugin.identity.messageid}});
trace("Here is the translated message : ", get(mytxtvar));



Advanced data input tags

feature

description This parameter has to be used inside a features node parameter.

It describes a feature that can be selected by the user, and all the parameters of this feature.

The children node of a feature can be any kind of parameter.

parameters 
 <features id="controls" name="tr:Available controls">
  <feature id="prevnext" name="tr:Previous/Next Panorama" enabled="true" guiIcon="btn_next_scene.png" crop="0|0|50|50">
    <string id="prevSceneTip" name="tr:Previous scene tooltip"  default="tr:Previous Scene"  conditionalParam="tooltips" conditionalValues="true"/>
    <string id="nextSceneTip" name="tr:Next scene tooltip"      default="tr:Next Scene"      conditionalParam="tooltips" conditionalValues="true"/>
  </feature>
  [...]
</features>

id : ID of the parameter

name : Feature label

enabled If true the feature will be enabled by default

forceEnabled If true the feature is a mandatory one. The user will not be allowed to unselect it.

guiIcon File name of an icon representing the feature

crop Crop a rectangular area of the guiIcon. If not set, the guiIcon is not cropped.

  • syntax : 
    crop="x-position|y-position|width|height"
usage 
{% if p.prevnext.enabled %}
  The Previous / Next feature is checked
{% else %}
  The Previous / Next feature is not checked
{% endif %}

plugin.prevnext.enabled true if the feature is selected


features

description Frame containing some feature parameters
parameters 
<features id="controls" name="tr:Available controls">
  <feature id="prevnext" name="tr:Previous/Next Panorama" enabled="true" guiIcon="btn_next_scene.png">
    <string id="prevSceneTip" name="tr:Previous scene tooltip"  default="tr:Previous Scene"  conditionalParam="tooltips" conditionalValues="true"/>
    <string id="nextSceneTip" name="tr:Next scene tooltip"      default="tr:Next Scene"      conditionalParam="tooltips" conditionalValues="true"/>
  </feature>
  [...]
</features>

id : ID of the parameter

name : Frame title

usage This parameter is only used in the GUI.



tooltipstyle

description Tooltip style definition
parameters 
      <tooltipstyle id="custom_tooltips_style" name="tr:Custom tooltip style" fontfamily="Arial" borderwidth="0" roundedge="0" displayBackground="false" fontsize="14" shadowed="true" fontstyle="bold">

id : ID of the parameter

name : Tooltip style label

fontfamily Default family name of the font

fontSize Default font size

fontstyle Default styles of the font : normal, bold, italic

borderwidth Default border width of the tooltip

roundedge If true, indicates that the tooltip background has round edges

displayBackground If true, indicates that the a background is displayed behind the tooltip

shadowed If true, indicates that a shadow is displayed behind the text of the tooltip


usage 
{% if p.custom_tooltips_style.value.roundEdge %}
	roundedge="{{p.custom_tooltips_style.value.roundEdge}}"
{% endif %}
{% if p.custom_tooltips_style.value.displayBackground %}
	background="true"
	backgroundcolor="0x{{p.custom_tooltips_style.value.bgColor}}"
	backgroundalpha="{{p.custom_tooltips_style.value.bgAlpha}}"
{%else%}
	background="false"
{% endif %}
{% if p.custom_tooltips_style.value.borderWidth %}
	border="true"
	borderwidth="{{p.custom_tooltips_style.value.borderWidth}}.0"
	bordercolor="0x{{p.custom_tooltips_style.value.borderColor}}"
	borderalpha="{{p.custom_tooltips_style.value.borderAlpha}}"
{% else %}
	border="false"
{% endif %}
{% if p.custom_tooltips_style.value.shadowed %}
{% if p.custom_tooltips_style.value.borderWidth %}
	shadow="1" shadowrange="4.0" shadowangle="45" shadowcolor="0x{{p.custom_tooltips_style.value.shadowColor}}" shadowalpha="{{p.custom_tooltips_style.value.shadowAlpha}}"
{% else %}
{% if p.custom_tooltips_style.value.displayBackground %}
	shadow="1" shadowrange="4.0" shadowangle="45" shadowcolor="0x{{p.custom_tooltips_style.value.shadowColor}}" shadowalpha="{{p.custom_tooltips_style.value.shadowAlpha}}"
{% endif %}
{% endif %}
	textshadow="1" textshadowrange="4.0" textshadowangle="45" textshadowcolor="0x{{p.custom_tooltips_style.value.shadowColor}}" textshadowalpha="{{p.custom_tooltips_style.value.shadowAlpha}}"
{% endif %}
	css="color:#{{p.custom_tooltips_style.value.fgColor}};font-family:{{p.custom_tooltips_style.value.fontFamily}};{% if p.custom_tooltips_style.value.fontItalic %}font-style:italic;{% endif %}{% if p.custom_tooltips_style.value.fontBold %}font-weight:bold;{% endif %}{% if p.custom_tooltips_style.value.fontUnderline %}text-decoration:underline;{% else %}{% if p.custom_tooltips_style.value.fontStrikeout %}text-decoration:line-through;{% endif %}{% endif %}font-size:{{p.custom_tooltips_style.value.fontSize}}px;text-align:left;"

UI layout tags

advanced

description This node is not really a parameter.

It allows to embed parameters in an advanced section of the parameters sheet in Panotour Pro.

This graphical section is closed by default.

All its embedded parameters should have a valid default value.

parameters 
<advanced id="advancedParam">
  <group id="onhoverbehaviour" name="tr:Behaviour on over" description="tr:Behaviour when the mouse is over the picture">
    <bool id="rescale" name="tr:Change picture size" default="false"/>
    <bool id="realpha" name="tr:Change transparency" default="false"/>
  </group>
</advanced>

id : ID of the parameter

usage This parameter is only used in the GUI


elementlist

description Allows the user to create multiple instances of a parameters, to create a list of identical parameters

Add "+"/"-" "up"/"down" controls at the end of the line to create a new instance of parameters and to sort them

The content of an element can be any type of parameters

parameters 
  <elementlist id="files">
  <filechooser id="file" name="tr:File" default="" filters="images"/>
</elementlist>

id : ID of the parameter

usage 
  There are {{plugin.files.nbelements}} files selected in the element list :
  {% for file in plugin.files.elements %}
    File n°{{forloop.counter}} : file.fileName
  {% endfor %}

plugin.files.nbelements Number of elements in the list

plugin.files.elements List of the elements


group

description Allows the developper to organize the parameters into Panotour GUI.

Parameters described as children of a "group" will be displayed in a frame with a title.

parameters 
  <group id="display" name="tr:Display" >
  <row id="displaytext">
    <font  id="font"  name="tr:Font"  default="Arial"   size="16" style="bold" />
    <color id="color" name="tr:Color" default="#ffffff" needalpha="true" defaultalpha="1.0" />
  </row>
  <row id="displayShadow">
    <bool id="hasshadow"  name="tr:Display a shadow behind the text" default="true" />
  </row>
</group>

id : ID of the group

name : Title of the frame in Panotour

usage This parameter is only used in the GUI.


label

description Allows the developper to add a text inside the plugin sheet.
parameters 
  <label id="warningMess" name="tr:The gyroscope plugin allows user to control the view by moving its mobile or tablet. It is only available on IPhone4 and IPad2." />

id : ID of the parameter

name : Text to display

usage This parameter is only used in the GUI.


row

description Allows the developper to organize the parameters into Panotour GUI.

Parameters described as children of a "group" will be displayed in a row.

parameters 
  <group id="display" name="tr:Display" >
  <row id="displaytext">
    <font  id="font"  name="tr:Font"  default="Arial"   size="16" style="bold" />
    <color id="color" name="tr:Color" default="#ffffff" needalpha="true" defaultalpha="1.0" />
  </row>
  <row id="displayShadow">
    <bool id="hasshadow"  name="tr:Display a shadow behind the text" default="true" />
  </row>
</group>

id : ID of the row

usage This parameter is only used in the GUI.


size

description Display dimensions parameters in a frame, and add "ratio" management on data involved
parameters 
<size id="thumbnailsize" name="tr:Thumbnail size" needkeepratio="false" defaultkeepratio="true" >
  <dimension id="thumbwidth"  name="tr:Width"  minimum="1" default="100" maximum="9999" availableunits="pixel" />
  <dimension id="thumbheight" name="tr:Height" minimum="1" default="50"  maximum="9999" availableunits="pixel" />
</size>

id : ID of the parameter

name : Title of the size frame

needkeepratio : If true, add a widget allowing to keep the ratio of the object

defaultkeepratio : Default value of the widget allowing to keep the ratio of the object

usage This parameter is only used in the GUI.



Binding actions

actionchooser

description Parameter widget allowing the user to choose an action
parameters 
    <actionchooser id="onclick" name="tr:Action" description="tr:Action done on click of the picture"/>

id : ID of the parameter

name : Parameter label

description : Description of the parameter

usage This parameter is not directly used in the template.

Embed it in an actionlist parameter.


actionlist

description This parameter has to be used with the actionchooser one.

It allows to select a list of actions.

The user can select an action with one actionchooser and add other actions by clicking on an Add button

parameters 
  <actionlist id="actions" name="tr:Actions done on a click of the picture" >
    <actionchooser id="onclick" name="tr:Action " description="tr:Action done on click of the picture"/>
</actionlist>

id : ID of the parameter

name : label of the frame in which are set the actionchooser parameters

usage 
{% if plugin.actions.actions.count %}
  <action name="{{plugname}}OnClick">
{%with plugin.actions.actions as actions%}
    {% include 'calltemplate.tmpl' %}
{%endwith%}
  </action>
{% endif %}

plugin.actions.actions.count Number of selected actions

plugin.actions.actions List of selected actions

calltemplate.tmpl Internal template that will parse the list of actions and write their call.












BACK TO: Documentation / Panotour Documentation

Retrieved from "http://www.kolor.com/wiki-en/index.php?title=Parameters_tags_documentation_(plug_info.xml)&oldid=28863"