close panorama

Actions / Scripting

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



It is possible to call more actions at once:

syntax:
action = action[;action]

the actions will be processed one after the other.



examples:
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


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*,...*) (Version 1.0.5 and higher)
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) (Version 1.0.6 and higher)
    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(xmlpath,parameter1*,parameter2*,...*) (Version 1.0.6 and higher)
- calls 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:
  • xmlpath
    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="call(events.myfu,hello from xml);" ...
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) (Version 1.0.4 and higher)
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
    it is possible to use simple html tags in the text, but some special characters like ',' or '<' and '>' and some more, needed to be escape-coded in form %HH, where HH is the hex code of the character.
    e.g.: '<' = %3C and '>' = %3E
    linebreaks: use '%3Cbr%3E' (=<br>) or just '\n'
  • textstyle (optional, Version 1.0.5 and higher)
    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\nline 2\nline 3);"
onhover="showtext(%3Cb%3Ebold%3C/b%3E %3Ci%3Eitalic%3C/i%3E);"

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))
moveto(10,10,smooth())
moveto(33,-22,smooth(100,50,20))

timerset(seconds,interval,var,startvalue,destvalue,
                 tweentype*,updatefu*,waitflag*,doneaction*)
(Version 1.0.2 and higher)
- 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*) (Version 1.0.5 and higher)
- 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
examples:
onclick="timerset(0.3,0,plugin[navimap].alpha,1,0,linear,,false,  
         set(plugin[navimap].visible,false););"

tweentypes for timerset and tween (Version 1.0.5 and higher)
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:
    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
    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
    sets onstart actions for the next panorama (decrepated)
    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:
....

loadxml(xmlstring,parameters*,flags*,blend*,onstart*) (Version 1.0.6 and higher)
- 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) (Version 1.0.6 and higher)
- 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>
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:
js file:
function jstest(testparameter) 
{
   alert(testparameter);
}

xml file:
... onclick="js(hello from xml);"