News • Examples • Documentation • Download • Buy • Forum • Contact
NOTE: This page is from an older version, switch to the latest version here.

krpano Actions / Scripting Reference Version 1.0.7

Actions / Functions / Commands that can be used on events or to script elements:




action calling syntax-definition in Extended Backus–Naur Form:
action ::= action[;action]
action ::= functionname([parameters])
parameters ::= parameter[,parameters]

  • it's very similar to standard coding langauges, like C/C++, Java, Javascript, Actionscript...
  • that means it is possible to call more actions at once, just separate or end each action with a semicolon ';'
  • the actions will be processed one after the other



example:
onclick="lookto(0,0,50);
         lookto(45,-10,70);
         zoomto(150);
         loadpano(next.xml);"
that means:
1. move the looking position to 0/0 with a field of view of 50°
2. move the looking position to 45/-10 with a field of view of 70°
3. zoom to field of view of 150°
4. load the "next.xml" panorama


example:
onclick="looktohotspot(spot1);
         loadpano(next.xml);"
that means:
1. move and zoom the view to center the hotspot
2. load the "next.xml" panorama


example:
onclick="lookto(88.517,1.097,6,smooth());
         loadpano(next.xml,null,KEEPBASE|NOPREVIEW,BLEND(1),
         lookat(180.8,1.9,22);
         wait(blend);
         lookto(263.711,0.982,87,smooth(100,20,50)); );"
that means:
1. move/zoom smoothly to position 88.517/1.097 with a field of view of 6°
2. load "next.xml", keep current settings, don't load the preview from "next.xml",
    overblend in 1 second
3. set current view to 180.8/1.9 with a field of view of 22°
4. wait until loading and blending have finished
5. move and zoom smoothly to 263.711/0.982 with a field of view of 87°


NEW in version 1.0.5 and higher:
Now the actions after a loadpano call are processed too!
So the onstart parameter of the loadpano call must not be used anymore!
This makes the code a better readable.

The same example as above now: (the difference is marked red)
onclick="lookto(88.517,1.097,6,smooth());
         loadpano(nextpano.xml,null,KEEPBASE|NOPREVIEW,BLEND(1));
         lookat(180.8,1.9,22);
         wait(blend);
         lookto(263.711,0.982,87,smooth(100,20,50));"


Description of the actions

action(actionname,parameter1*,parameter2*,...*)
executes the actions defined in the action tag named "actionname"

parameters:
  • actionname
    the name of the action tag
    see xml action tag documentation
  • parameters* (optional)
    optional parameters for the action
    this parameters replace the %N placeholders in the action tag
    e.g.:
    first parameter replaces the %1 in the action
    second parameter replaces the %2 in the action
    and so on...
example - zoom to a position, load and blend to the next pano, look to a new position
<action name="loadpano1">
    lookto(88,20,30);
    loadpano(nextpano.xml,null,KEEPALL,BLEND(1));
    lookat(180,0,30);
    wait(blend);
    lookto(1801,0,130,smooth(100,20,50));"
</action>
	
<hotspot ...
         onclick="action(loadpano1);"
         />
example - scale up a buttons on mouse over, scale down on mouse out
<action name="scaleup">
   tween(plugin[%1].width,75,distance(25,0.2),easeoutcubic);
   tween(plugin[%1].height,75,distance(25,0.2),easeoutcubic);
</action>
	
<action name="scaledown">
   tween(plugin[%1].width,50,distance(25,0.2),easeincubic);
   tween(plugin[%1].height,50,distance(25,0.2),easeincubic);
</action>
	
<plugin name="button1" url="button1.png" ...
        onover="action(scaleup,button1);" 
        onout="action(scaledown,button1);" 
        />
<plugin name="button2" url="button2.png" ...
        onover="action(scaleup,button2);" 
        onout="action(scaledown,button2);" 
        />
call(path,parameter1*,parameter2*,...*)
UPDATE NOTES 1.0.7 - functions can now also be called direct, without call()

e.g. just: 
plugin[maps].pantospot(spot1);
instead of: 
call(plugin[maps].pantospot,spot1);


- call a flash "action script 3" function
- this function can be a predefined function or
- it can be assigned from a plugin
- can be used to communicate from xml to plugins/as3 functions

parameters:
  • path
    path to the function
    e.g. "plugin[image].changeorigin"
  • parameters* (optional)
    optional parameters for the function
    the parameters are passed as strings to the as3 function
example - change the origin position of a plugin but keep the current position at screen
call(plugin[logo].changeorigin,rightbottom,center);

example - call a as3/plugin function:
as3/plugin code: 
function myfunction(p1:String)
{
  // ... do something ...
}

krpano.set("events.myfu", myfunction);
xml code: 
... onclick="events.myfu(hello from xml);" ...
delayedcall(delay,actions...)
calls/executes a set of actions after a given time

parameters:
  • delay
    number of seconds to wait before executing the actions
  • actions...
    action commands to execute
example:
<krpano ... onstart="delayedcall(5, action(hidelogo); );">
set(variable,value)
set the "variable" to "value"

parameters:
  • variable
    any variable listed in the API documentation
  • value
    the new value for this variable

examples:
set(view.fov,120)   - set field of view to 120 degree
set(display.fps,60) - set framerate to 60 frames per second
set(plugin[button].visible,false) - hides a button
switch(variable,valueA,valueB)
Switches a the "variable" between two values ("valueA","valueB")
Without the "valueA" and "valueB" parameters it swtiches between "true" and "false".

parameters:
  • variable
    a API varible, e.g. "plugin[name].visible"
  • valueA (optional)
  • valueB (optional)

for all available parameters have a look at the API documentation

examples:
switch(fullscreen); - switches fullsceen mode on/off
switch(hotspot.visible); - switches all hotspots on/off
switch(plugin[button1].visible); - switches button1 on/off
switch(plugin[button1].alpha,1,0.5);
 - switches the alpha value between 1 and 0.5
push(variable)
pop(variable)
push - saves the value of "variable" to stack
pop  - restores the value of "variable" from stack

NOTE: stack is based on the principle of Last In First Out (LIFO)
showtext(text,textstyle*)
shows the "text" at the current mouse position or on screen coordinates

parameters:
  • text
    • the text to show
    • html tags can be used in the text
    • but using html characters like '<' and '>' is not possible!
    • use '[' and ']' instead of it
    • for language specific characters use a set the Encoding of XML file or use a Unicode UTF8 or UTF16 XML file

    NOTE - to use some special characters like ',' or '<' and '>' they needed to be escape-coded in form %HH, where HH is the hex code of the character.
    e.g.: ',' = %2C
    for linebreaks just use [br] (=<br>) or '\n'

    examples tags for formating:
    • [b]bold[/b]
      - bold text
    • [i]italic[/i]
      - italic text
    • [u]underline[/u]
      - underlined text
    • [br]
      - linefeed
  • textstyle (optional)
    the name of the textstyle to use for this text,
    if not defined the DEFAULT style is used
    see xml textstyle tag documentation
examples:
onhover="showtext(you are hovering me);"
onhover="showtext(style text,TEXTSTYLE);"
onhover="showtext(line 1[br]line 2[br]line 3);"
onhover="showtext([b]bold[/b] [i]italic[/i]);"

DEMO: view some textstyles interactive

lookat(atH,atV,fov)
look at this panorama position

parameters:
  • atH
    horizontal position in degrees, spherical coordinates (0 .. 360°)
  • atV
    vertical position in degrees, spherical coordinates (-90 .. +90°)
  • fov
    field of view in degrees (1 .. 179°) (optional)
examples:
lookat(0,0,140)
lookat(34.25,-11.2,45.3)
setfov(fov)
set the current field of view

parameters:
  • fov
    field of view in degrees (1 .. 179°)
example:
setfov(90.0)

moveto(toH,toV,motiontype)
zoomto(fov,motiontyp)
lookto(toH,toV,fov,motiontype)
moves the view from current to the given position

parameters:
  • toH
    destination coordinate (-360 .. 360°)
  • toV
    destination coordinate (-90 .. +90°)
  • fov
    destination field of view (1 .. 179°)
  • motiontype (optional)
    can be:
    linear(speed) - linear movement
    - speed = moving speed in degrees/second

    smooth(accel,break,maxspeed) - accelerated smooth movement (=default)
    - accel = acceleration in degrees/second² (default=720)
    - break = negative acceleration in degrees/second² (default=-720)
    - maxspeed = maximum moving speed in degrees/second (default=720)
examples:
moveto(100.0,5,linear(10));
zoomto(130,smooth());
lookto(33,-22,30,smooth(100,50,20));

looktohotspot(hotspotname,fov*,motiontype*)
moves the view to the center of the hotspot

parameters:
  • hotspotname
    name of the hotspot
  • fov (optional)
    destination field of view
    can be "auto" or a value from 1 .. 179°
    default is "auto" - there the fov is calculated from the size of the hotspot
  • motiontype (optional)
    can be:
    linear(speed) - linear movement
    - speed = moving speed in degrees/second

    smooth(accel,break,maxspeed) - accelerated smooth movement (=default)
    - accel = acceleration in degrees/second² (default=720)
    - break = negative acceleration in degrees/second² (default=-720)
    - maxspeed = maximum moving speed in degrees/second (default=720)
examples:
looktohotspot(hotspot_1);
looktohotspot(hotspot_2, 40);
looktohotspot(hotspot_3, 25, smooth(100,50,20));

timerset(seconds,interval,var,startvalue,destvalue,
                 tweentype*,updatefu*,waitflag*,doneaction*)
- changes the value of an API variable in intervals
- it interpolates from the start value to an destination value
- if a other timerset/tween is already modifying the same value it will be stoped

parameters:
  • seconds
    • time to run in seconds, default=0.5
    • it is possible to use here a special function that calculates the time depending on the distance between the start and destination value:

      distance(maxdistance,maxtime)
      • maxdistance - the maximum distance between start and destination values
      • maxtime - the time in seconds for this maximum distance
      now depending on the current value/position the needed time will be automatic fitted, this is usefull when a other timerset or tween was interrupted.
  • interval
    interval in seconds to update the value, 0=every frame
  • var
    the name of the variable to change
  • startvalue
    start value for var, let this parameter empty to get current value
  • destvalue
    destination value for the variable
  • tweentype (optional)
    interpolation type, default="linear"
    have a look here for all available tween types: tweentypes
  • updatefu (optional)
    "screen" to refresh, "view" to redraw, default=""
  • waitflag (optional)
    wait until done (user control will be blocked in this time)
    default=true
  • doneaction (optional)
    action to call when done
examples:
onclick="timerset(0.3,0,plugin[navimap].alpha,1,0,linear,,false,  
         set(plugin[navimap].visible,false););"

tween(var,destvalue,time*,tweentype*,donecall*)
- this is a short form of the timerset action
- it changes the current value of an API variable to a destination value
- if a other timerset/tween is already modifying the same value it will be stoped

parameters:
  • var
    the name of the variable to change
  • destvalue
    destination value for the variable
  • time (optional)
    • time to run in seconds, default=0.5
    • it is possible to use here a special function that calculates the time depending on the distance between the start and destination value:

      distance(maxdistance,maxtime)
      • maxdistance - the maximum distance between start and destination values
      • maxtime - the time in seconds for this maximum distance
      now depending on the current value/position the needed time will be automatic fitted, this is usefull when a other timerset or tween was interrupted.
  • tweentype (optional)
    interpolation type, default="easeoutquad"
    have a look here for all available tween types: tweentypes
  • donecall (optional)
    action to call when done
example - fade out a plugin by changing it's alpha value to 0
<plugin ...
        onclick="tween(alpha, 0);" 
        />
example - change the size of hotspot on onover and onout
<hotspot ... 
         onover="tween(scale, 1.5);" 
         onout ="tween(scale, 1.0);" 
         />
example - change the position of a other plugin (button)
<plugin ...
        onclick="tween(plugin[button].x, 0);
                 tween(plugin[button].y, 0);" 
        />

tweentypes for timerset and tween
interpolation / tween types:
  • linear
  • easeInBounce
  • easeInCirc
  • easeInCubic
  • easeInExpo
  • easeInOutBounce
  • easeInOutCirc
  • easeInOutCubic
  • easeInOutExpo
  • easeInOutQuad
  • easeInOutQuad
  • easeInOutQuart
  • easeInOutQuint
  • easeInOutSine
  • easeInQuad
  • easeInQuad
  • easeInQuart
  • easeInQuint
  • easeInSine
  • easeOutBounce
  • easeOutCirc
  • easeOutCubic
  • easeOutExpo
  • easeOutInBounce
  • easeOutInCirc
  • easeOutInCubic
  • easeOutInExpo
  • easeOutInQuad
  • easeOutInQuart
  • easeOutInQuint
  • easeOutInSine
  • easeOutQuad
  • easeOutQuad
  • easeOutQuart
  • easeOutQuint
  • easeOutSine

have a look at these sites for a online visualization of this tweentypes:

http://hosted.zeh.com.br/tweener/docs/en-us/misc/transitions.html
http://hosted.zeh.com.br/mctween/animationtypes.html

load / loadpano(xmlpath,parameters,flags,blend,onstart)
- loads a new panorama xml file
- or loads direct a other panorama image without xml file

parameters:
  • xmlpath
    path of the panorama xml file ("null" for none)
  • parameters
    direct parameters like "sphere=image.jpg&view.fov=120" ...
  • flags
    - flags for loading (optional, "null" for none)
    - more flags can be combinated with a '|'

    possible flags:
    • MERGE (1.0.7 an higher)
      • merges all settings from the current and the next pano
      • plugins / hotspots / lensflare without keep="true" are removed
      • if there are plugins and hotspots in the new panorama with the same name as the kept ones, the new ones are not loaded
      • this is the recommended setting for new virtual tours
    • KEEPVIEW - keep current view settings (1.0.5 an higher)
    • KEEPDISPLAY - keep current display settings
    • KEEPCONTROL - keep current control settings
    • KEEPPLUGINS - keep current loaded plugins
    • KEEPHOTSPOTS - keep current loaded hotspots
    • KEEPPROGRESS - keep current progress settings
    • NOPREVIEW - ignore the <preview> tag of the new xml (note)
    • KEEPBASE - a predefined combination of:
        KEEPDISPLAY | KEEPCONTROL | KEEPPLUGINS | KEEPPROGRESS
    • KEEPALL - a predefined combination of:
        KEEPVIEW | KEEPDISPLAY | KEEPCONTROL | KEEPPLUGINS | KEEPPROGRESS

  • blend
    - blend to next panoroma (optional)

    possible blending modes:
    - NOBLEND = no blending (=default)
    - BLEND(n) = blends from current panorama to next in "n" seconds
    - ZOOMBLEND(n,z) = zooms and blends in "n" seconds with zoom factor "z"
  • onstart (decrepated)
    sets onstart actions for the next panorama
    see - new in 1.0.5 notes
Notes - NOPREVIEW:
If you use the wait(load) action and NOPREVIEW the wait action waits until the main panorama image is completly loaded, before continuing on next actions or on interacting in the pano.
But without NOPREVIEW the the wait(load) action only waits until the preview image is loaded!

examples:
loadpano(nextpano.xml, null, MERGE, BLEND(2));

loadxml(xmlstring,parameters*,flags*,blend*,onstart*)
- passes the content of a xml file as string for loading

parameters:
  • xmlstring
    the xml as string, should be escape-coded
  • ...other parameters... (optional)
    the same like in the loadpano() action
reload / reloadpano()
- reloads the current panorama

if you change some parameters like "image.sphere.url" or "image.type"
the panorama must be reloaded to take effect.
see the API documentation for "load only" variables, these variables will be only parsed on loading.
wait(arg)
- wait until something is finished (user control will be blocked in this time)

parameters:
  • arg
    if arg is a number -> this the time it will wait in seconds
    if arg is "load" -> wait until loading is finished
    if arg is "blend" -> wait until loading and blending are finished
example - use wait to stop some seconds
<action name="autotour">
   oninterrupt(break);
   lookto(150,30,70);
   wait(3);
   lookto(242,0,150);
   lookto(280,-10,50);
   wait(3);
   ...
</action>
example - wait until loading and blending is done
<action name="loadpano">
   loadpano(pano2.xml,null,KEEPALL|NOPREVIEW,BLEND(2));
   lookat(100,50,5);
   wait(blend);
   lookto(100,50,150);
</action>
freezeview(state)
- freezes the current view and blocks user control
- this increases the performance of elements that will be drawn on top of the pano

parameters:
  • state
    true - freezes the view
    false - restores normal state
example:
...
stop / stopall()
- stops/breaks all current running actions/timersets/tweens
- removes the rest of the queued actions
breakall()
- stops/breaks all current running actions/timersets/tweens
- continues with the rest of the queued actions
oninterrupt(newaction)
- this function can be set before starting a lot of action calls
- it was called when a mouse click interrupts one of following actions
- after interrupting or processing all actions, this function will be disabled until next call

parameters:
  • newaction
    • actions to call on interrupt
    • there is a special case action - "break"
      - this will break the current actions
example - break all following actions
<action name="autotour">
   oninterrupt(break);
   lookto(150,30,70);
   wait(3);
   lookto(242,0,150);
   lookto(280,-10,50);
   wait(3);
   ...
</action>
example - continue on a other action
<action name="autotour">
   oninterrupt(action(returnaction));
   lookto(150,30,70);
   wait(3);
   lookto(242,0,150);
   lookto(280,-10,50);
   wait(3);
   ...
</action>

<action name="returnaction">
   lookto(0,0,90);
</action>
trace(message)
- shows a info message on the log window

parameters:
  • message
    the message to show
error(errormessage)
- shows a fatal error message and stops panorama viewing

parameters:
  • errormessage
    the error message to show
url / openurl(url,target)
- opens an external url

parameters:
  • url
    url to open (should be absolute, e.g. http://...)
  • target
    specify where the link will be loaded (optional, default=_blank)
example:
onclick="openurl(http://www.krpano.com,_self);"
example:
onclick="openurl(http://krpano.com/docu/actions/#openurl,_blank);"
js / javascript( jsfunction(parameters*) )
calls a javascript function

parameters:
  • jsfunction
    the javascript function
  • parameters (optional)
    parameters for the javascript function

also have a look at the javascript documentation: javascript interface
example:
html / js file:
function jstest(p1, p2) 
{
   alert("p1=" + p1 + "\np2=" + p2);
}

xml file:
... onclick="js( jstest(hello from xml, second parameter) );"

updateobject()
- updates / rebuilds the internal pano 3D object
- this action must be after changes of the display.details or display.tessmode settings
example - changes details and update:
set(display.details,22);
updateobject();
updatescreen()
- force a redraw of the panorama
- the quality is not changed
invalidatescreen()
- force a redraw of the panorama
- the quality is change to movequality

addplugin(name)
adds and creates a new plugin object

parameters:
  • name
    name of the new plugin, needed for access to it
example - add and setup a new plugin:
addplugin(button);
set(plugin[button].url,button.jpg);
set(plugin[button].align,bottom);
set(plugin[button].x,10);
set(plugin[button].y,20);
set(plugin[button].onhover,showtext(hovering new button));
set(plugin[button].onclick,action(buttonclick));
removeplugin(name)
removes a plugin object

parameters:
  • name
    name of the plugin be to removed
example:
removeplugin(button);
addhotspot(name)
adds and creates a new hotspot object

parameters:
  • name
    name of the new hotspot, needed for access to it
example - add and setup a new image hotspot:
addhotspot(newspot);
set(hotspot[newspot].url,spot.png);
set(hotspot[newspot].ath,150);
set(hotspot[newspot].atv,30);
set(hotspot[newspot].scale,0.7);
set(hotspot[newspot].zoom,true);
set(hotspot[newspot].onhover,showtext(hovering new hotspot));
set(hotspot[newspot].onclick,action(hotspotclick));
example - add and setup a new polygonal hotspot:
addhotspot(newspot);
set(hotspot[newspot].fillalpha, 0.25);
set(hotspot[newspot].borderalpha, 0.50);
set(hotspot[newspot].onhover,showtext(hovering new hotspot));
set(hotspot[newspot].onclick, removehotspot(newspot) );
set(hotspot[newspot].point[0].ath,-10);
set(hotspot[newspot].point[0].atv,-10);
set(hotspot[newspot].point[1].ath,-10);
set(hotspot[newspot].point[1].atv,+10);
set(hotspot[newspot].point[2].ath,+10);
set(hotspot[newspot].point[2].atv,+10);
set(hotspot[newspot].point[3].ath,+10);
set(hotspot[newspot].point[3].atv,-10);
removehotspot(name)
removes a hotspot object

parameters:
  • name
    name of the hotspot to be removed
example:
removehotspot(newspot);
addlensflare(name,atH,atV)
adds and creates a new lensflare object

parameters:
  • name
    name of the new lensflare, needed for access to it
  • atH
    horizontal position in degrees, spherical coordinates (0 .. 360°)
  • atV
    vertical position in degrees, spherical coordinates (-90 .. +90°)
example - add and setup a new lensflare:
addlensflare(lf1, 10, 20);
set(lensflare[lf1].set,  FLARESET2);
set(lensflare[lf1].size, 0.7);
removelensflare(name)
removes a lensflare object

parameters:
  • name
    name of the lensflare to be removed
example:
removelensflare(lf1);