close panorama

krpano Actions / Scripting Reference Version 1.17.1

krpano has a small and simple dynamic scripting language. With it krpano can be customized in many ways. A command or function is called action in krpano. It's possible to use existing actions and also to define new ones. The scripting language is dynamic and basically untyped, only some predefined variables are typed, but that is normally not relevant because inside the scripts all type conversions will be done automatically.

About this documentation

This documentation is about global krpano variables and objects, about the actions calling syntax and about all pre-defined krpano actions / functions.

Documentation topics:

krpano Global-Variables Reference

Version / Build information Screen information / settings Device informations Mouse / Keyboard Timing / Random values Math constants Keyboard / Button moving Multiresolution information XML / Scene Debugging / Error handling Layers (Flash only)

krpano Actions / Functions Reference

Programming logic / Flow control Math operators Number / String formating Animations / Animated value changing Dynamic loading of other panos (tours) Viewing animations / Camera control Coordinate transformation Text visualization View / Pano updates Dynamic adding or removing of visible elements Plugin / Hotspot Actions External / Javascript Interface Debugging

Syntax and Usage

The calling conventions of krpano actions / functions:

actionname(parameters);
  • The actionname can be either:
    • the name of a predefined krpano action or...
    • the name of an <action> element that was defined anywhere in the xml or...
    • the name of a krpano variable/attribute that contains krpano action code.
  • It's possible to call severals actions at once, just end each action with a semicolon ;.
  • The actions will be processed one after the other.
  • 'White'-spaces (like spaces, tabs and new lines) between action calls and between parameters will be ignored.
  • The number of parameters to use depend on the called action.
  • Parameters need to be separated by commas ,.
  • To be able to use white-spaces and commas in a parameter, the parameter must be enclosed by single ' or double quotes ".
  • The given parameters are passed as texts to the action. When the given parameter is the name of a variable, then the variable will be NOT resolved automatically to its value! Some actions are resolving variables automatically, but this depends on the action itself. To force resolving a variable and passing only the content/value of the variable use the get action.
  • Have also a look to this great and very detailed explanations from pinsane about the krpano actions and their arguments/parameters in the krpano forum.

Global Variables

Meaning and usage of the global krpano variables:
variable name (read only)typedefault value
version String
The krpano version string, e.g. "1.17".
variable name (read only)typedefault value
xmlversion String
The version setting from the xml. When not set this will be the same number as the krpano version string.
variable name (read only)typedefault value
build String
The krpano build string, e.g. "2013-03-28".
variable names (read only)typedefault value
mouse.x
mouse.y
mouse.stagex
mouse.stagey
int
int
int
int
The current mouse position.
The mouse.x and mouse.y coordinates are relative to the left top edge of the area and the mouse.stagex and mouse.stagey coordinates to the left top edge of the whole stage/window.
variable name (read only)typedefault value
keycode int 0
The keycode of the last pressed or released key.
It will be set in the onkeydown and onkeyup events.

Note - here a small code snippet to find out the keycode of the pressed key:
<events onkeydown="showlog(); trace('keycode=',keycode);" />
variable name (read only)typedefault value
wheeldelta int 0
The delta of the mouse wheel rotation.
This variable will be set in the onmousewheel event.
variable name (read only)typedefault value
wheeldelta_raw Number Number.NaN
The 'raw' unscaled and non-rounded delta value of the mouse wheel rotation.
The normal wheeldelta values are limited to integer values and can be too inaccurate for some usages (plugins).

Note - in the krpano Flash viewer, the raw values are only available when using the default krpano embedding script and only in windowed-mode (not in Fullscreen mode)! In the krpano HTML5 viewer, the raw values are always available.
variable nametypedefault value
fullscreen Boolean false
The fullscreen variable holds the current state of the fullscreen mode.
When it will be changed, then also the fullscreen mode will change.

Note - there is a Flashplayer security limitation - switching to fullscreen mode is only possible as reaction of an user input like a mouse click or a keypress! That means you can only switch to fullscreen mode in a onclick or onkeydown event.

Example - switch to fullscreen mode:
onclick="set(fullscreen,true);"
Example - switch between fullscreen and windowed mode:
onclick="switch(fullscreen);"

Note - before using the fullscreen setting, it should be verified if the current browser/device actually supports the Fullscreen mode. This can be done with the xml fullscreensupport devices setting and the device.fullscreensupport variable.

HTML5 Notes - when the HTML5 Fullscreen Mode is NOT supported by the browser, then the fullscreen setting will only change the size of the viewer html element to match the size of the full browser window. Due technical limitations this will not working from inside an <iframe> and can be problematic in nested html structures.
variable names (read only)typedefault value
stagewidth
stageheight
int
int
The size of the current window in pixels.
Get the this size in the onresize event.
variable names (HTML5 only)typedefault value
stagescale Number 1.0
A global overall scaling setting.
The stagescale setting will scale all krpano elements and sizes.

By scaling all elements, the krpano stage-size (screensize/resolution) itself will be scaled inversely by this value - e.g. a value of 0.5 will scale-down all elements by 50%, while increasing the internal stage-sizes by 200% at the same time.

The default stagescale value depends on the device, the browser, the Javascript window.devicePixelRatio value and the viewport scaling.
On desktop and many tablets the default value will be 1.0, on iPhone 0.5 and on many Android mobiles something between 0.5 and 0.75.
variable name (read only)typedefault value
browser.useragent String
The user-agent string of the browser.
The same as navigator.userAgent in Javascript.

Note - this string will be only available when using the default embedding script.
variable name (read only, html5 only)typedefault value
browser.platform String
The platform string of the browser.
The same as navigator.platform in Javascript.
variable names (read only)typedefault value
device.flash
device.flashversion
device.html5
device.desktop
device.mobile
device.tablet
device.css3d
device.webgl
device.fullscreensupport
device.pixelratio
device.touchdevice
device.gesturedevice
device.ios
device.iosversion
device.iphone
device.ipod
device.ipad
device.retina
device.android
device.androidversion
device.androidstock
device.blackberry
device.chrome
device.chromeversion
device.firefox
device.firefoxversion
device.ie
device.ieversion
device.safari
device.safariversion
device.opera
device.operaversion
device.air
device.standalone
device.windows
device.mac
device.linux
Boolean
Number
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Number
Boolean
Boolean
Boolean
Number
Boolean
Boolean
Boolean
Boolean
Boolean
Number
Boolean
Boolean
Boolean
Number
Boolean
Number
Boolean
Number
Boolean
Number
Boolean
Number
Boolean
Boolean
Boolean
Boolean
Boolean
false

false
false
false
false
false
false
false
1.0
false
false
false

false
false
false
false
false

false
false
false

false

false

false

false

false
false
false
false
false
The device object provides information about the current device/system. It's the dynamic/scripting equivalent to the xml devices attribute.
The attributes/properties of the device object can be checked anytime by scripting code, e.g. by the if() action.

The device object has these properties:
  • flash - true only in the krpano Flash viewer
  • flashversion - version of the Flashplayer (Flash only)
  • html5 - true only in the krpano HTML5 viewer
  • desktop - true only on Desktop
  • mobile - true only on Mobiles
  • tablet - true only on Tablets
  • css3d - true when CSS-3D-Transforms are available (HTML5 only)
  • webgl - true when WebGL is available (HTML5 only)
  • fullscreensupport - true only when the Fullscreen-mode is support
  • pixelratio - the pixelratio of the device/browser
  • touchdevice - true only on Touch devices
  • gesturedevice - true only on Gesture (Multi-Touch) devices
  • ios - true only on iOS devices (iPhone, iPod, iPad)
  • iosversion - the iOS version of the device (iPhone,iPad,iPod only)
  • iphone - true only on the iPhone (and iPod Touch)
  • ipod - true only on the iPod Touch
  • ipad - true only on the iPad
  • retina - true only on iOS retina displays
  • android - true only on Android devices
  • androidversion - the Android version (HTML5 only)
  • androidstock - true only in 'stock' (=WebView-based) Android browsers
  • blackberry - true only on BlackBerry devices
  • chrome - true only in the Chrome browser (HTML5 only)
  • chromeversion - version of the Chrome browser (HTML5 only)
  • firefox - true only in the Firefox browser (HTML5 only)
  • firefoxversion - version of the Firefox browser (HTML5 only)
  • ie - true only in the Internet Explorer browser (HTML5 only)
  • ieversion - version of the Internet Explorer browser (HTML5 only)
  • safari - true only in the Safari browser (HTML5 only)
  • safariversion - version of the Safari browser (HTML5 only)
  • opera - true only in the (Presto-based) Opera browser (HTML5 only)
  • operaversion - version of the Opera browser (HTML5 only)
  • air - true only in the Adobe AIR Player
  • standalone - true only in the Standalone Flashplayer
  • windows - true only on Windows systems
  • mac - true only on Mac OSX systems
  • linux - true only on Linux systems

Examples
if(device.html5, ...);
if(device.flash, ...);
if(device.android, if(device.flash, ...); );
if(device.iOSversion GT 5.1, ...);
variable names (read only)typedefault value
isflash
ishtml5
ismobile
istablet
isdesktop
isphone
ispad
isandroid
istouchdevice
isgesturedevice
iosversion
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
String
false
false
false
false
false
false
false
false
false
false
"0"

Note - these variables are deprecated - use the new device object instead!

Global device detection variables.
  • isflash - true only in the Flashplayer (Desktop and Android)
  • ishtml5 - true only in the krpanoJS (HTML5) viewer
  • ismobile - true only on an iPhone/iPod and on Android Mobile devices
  • istablet - true only on an iPad and on Android Tablet devices
  • isdesktop - true only on Desktop (Flash and HTML5) viewer
  • isphone - true only on the iPhone (and iPod Touch)
  • ispad - true only on the iPad
  • isandroid - true only on Android devices
  • istouchdevice - true only on Touch devices (iPhone,iPad,Android)
  • isgesturedevice - true only on Gesture (Multi-Touch) devices
  • iosversion - the iOS version of the device (iPhone,iPad,iPod only)
variable name (read only)typedefault value
timertick int
The timertick variable returns the number of milliseconds that have elapsed since the viewer was started (1000 milliseconds = 1 second).
variable name (read only)typedefault value
random Number 0.0 - 1.0
The random variable returns the a random number in range 0.0 to 1.0.

Example - how to get a random value in the range 1 - 10:
mul(val, random, 9);
add(val, 1);
roundval(val);
trace('random value=',val);
variable namestypedefault value
hlookat_moveforce
vlookat_moveforce
fov_moveforce
Number
Number
Number
0.0
0.0
0.0
These variables are defining a moving force to move the view / the pano.

When set to a value other than 0.0 the view will start slowly accelerating (controlled by keybaccelerate) and move with a maximum speed (controlled by keybspeed) until set back to 0.0, then it will slow down (controlled by keybfriction).
variable name (read only)typedefault value
multireslevel int
The multireslevel variable returns the current multi-resolution level
(0 - image.level.count).
variable nametypedefault value
lockmultireslevel String -1
Lock the automatic multi-resolution level selection to a fixed level.
Set lockmultireslevel to "current" to lock the level to the current level. To release the level locking set lockmultireslevel back to "-1".
variable nametypedefault value
downloadlockedlevel Boolean false
When set to true then the locked level will be downloaded completely.
variable name (read only)typedefault value
xml.url String
The xml.url variable contains the path/url of the currently loaded xml file.
variable name (read only)typedefault value
xml.content String
The xml.content variable contains the whole content of the currently loaded xml file as string.
variable name (read only)typedefault value
xml.scene String
The xml.scene variable contains the name of currently loaded scene.
variable name (read only)typedefault value
lasterror String
The lasterror variable contains the last error message when an error had happened. To get this variable the onloaderror event must be used.
variable name (read only)typedefault value
haveexternalinterface Boolean true
This variable can be used to check if the External Interface from the Flashplayer is available. This interface is necessary for the Javascript Interface and for the openurl actions.
Online on a server the External Interface is always available, but locally only when Flash file will be opened inside the Browser and when the folder of the Flash swf is in a 'trusted folder'. The trusted folders can be managent in the Flashplayer security settings, see here for more detatils - Local / Offline Usage.
variable name (read only)typedefault value
havenetworkaccess Boolean true
This variable can be used to check if the Network Access is available in the Flashplayer. This can be used to avoid errors when trying to use plugins like the Google Maps or Bing Maps locally, because these plugins are trying to load data from the web and so need Network Access.
Online on a server the Network Access is always available, but locally only when the folder of the Flash swf is in a 'trusted folder'. The trusted folders can be managent in the Flashplayer security settings, see here for more detatils - Local / Offline Usage.


Action Documentations

set(variable, value)
Set the given 'variable' to the given 'value'.

Note - when the name of "value" is a variable, it will be NOT resolved automatically!
To get the content of a variable the get(variable) function need to be used!


Parameters:
  • variable
    Any variable name.
    When the variable doesn't exists it will be created.

  • value
    The new value for this variable.
Examples
set(var1, 'hello');
set(var2, get(var1));
set(fullscreen, true);
set(layer[p1].visible, false);
set(hotspot[h1].scale, 2.5);
set(contextmenu.item[0].caption, 'hello item');
set(events.onxmlcomplete, null);
get(variable)
Resolves the 'variable' to its value.

The get(var) action is a special action that can be only used as parameter when calling an other action or inside an array access [ ] operator!

Note - some actions automatically try to resolve given parameters to their value, there using get() is not necessary!

Parameters:
  • variable
    Any variable.
    When the variable doesn't exists, then get() will return null.
Examples
set(dstvar, get(srcvar));
looktohotspot(get(name));
lookto(get(h), get(v), get(f));
showtext(get(msg));
tween(var,get(dstval));
set(pic, spot1);
set(hotspot[get(pic)].visible, false);
trace('xyz=', xyz, ' get(xyz)=', get(xyz));
txtadd(msg, 'fov=', get(view.fov));
copy(destination, source)
The copy() action copies the content from one variable to the other one.
This is the same like:
set(destination, get(source) )


Parameters:
  • destination
    The destination variable.
    When the variable doesn't exists it will be created.
  • source
    The source variable.
    When the variable doesn't exists, null will be set to the destination variable.
Examples
copy(dstvar, srcvar);
copy(cur_hlookat, view.hlookat);
copy(layer[text].x, mouse.x);
copy(layer[text].y, mouse.y);
delete(variable, ...)
Delete and remove the given variables.

Parameters:
  • variables
    Any variable name.
    Can be passed more than once.
Examples
set(tmp1, ...);
set(tmp2, ...);
... do something ...
delete(tmp1, tmp2);
if(condition, then-actions, else-actions*)
ifnot(condition, then-actions, else-actions*)
The if() action allows a conditional execution of code.
If actions can be nested infinitely within other if actions, this provides a complete flexibility for conditional code execution.

Parameters:
  • condition - the condition to check
    When the result of the condition is true, then the then-actions will be executed, and when the condition is false, then the else-actions.

    There are two types of conditions possible:
    1. Checking one variable:
      if(variable, ...);
      Test if this variable is true or 'not 0' or 'not null'.

    2. Comparing two variables or values:
      if(var1 OPERATOR var2, ...);
      The var1 or var2 can be a variables or values. When var1 or var2 is a variable then the content of the variable will be used for comparison. Only when using a 'strict' comparison operator (=== or !==) then var1 and var2 must be variables (or null).

      Available operators:
      ==equal
      !=not equal
      <  or  LTlower than *
      >  or  GTgreater than *
      <=  or  LElower or equal than *
      >=  or  GEgreater or equal than *
      ===strict equal (compare only existent variables)
      !==strict not equal (compare only existent variables)
      * Note - because of xml limitations, the usage of '<' and '>' characters is not possible every time!

  • then-actions
    The krpano actions that will be executed when the condition is true.

  • else-actions (optionally)
    The krpano actions that will be executed when the condition is false.

Notes - about the then/else actions - there can be several actions, not only one! Each action command must end with a semicolon then the next action command can follow!
Examples
if(fullscreen, fullscreensetup(), windowsetup() );
if(fullscreen, set(layer[controls].visible, false) );
if(%1 != next, set(i,0) );
if(i LT 10, loop(next) );
if(var === null, set(var,0));
if(hotspot[spot1] === null, trace(there is no spot1 hotspot));
if(varA GT 5,
    if(varA LT 10,
        trace('varA is between 5 and 10')
      );
  );
set(result,true);
ifnot(varA, set(result,false) );
ifnot(varB, set(result,false) );
ifnot(varC, set(result,false) );
if(result, trace('all vars are true') );
if(var1 GT var2,
    trace('condition is true');
    lookto(100,20,50);
  ,
    trace('condition is false');
    lookto(0,0,100);
  );
resolvecondition(variable, condition)
resolvecondition(variable, conjunction, condition)
The resolvecondition() action works like the if() action, but just instead of calling different actions, the result of the condition resolving will be stored in the given variable. Additionally it's possible to use a logical conjunction to mix the result with the value of the given variable.

Parameters:
  • variable
    The name of the variable where the result will be stored.
    The result will be always true or false.
    When the variable doesn't exists it will be created.

  • conjunction (3-parameter-call only)
    Use a logical conjunction to mix the result of the condition with the value of the given variable.

    Available conjunctions:
    ANDvariable = variable AND condition-result
    ORvariable = variable OR condition-result
    XORvariable = variable XOR condition-result

  • condition
    The condition to check.

    There are two types of conditions possible:
    1. Checking one variable:
      resolvecondition(result, variable);
      Test if this variable is true or 'not 0' or 'not null'.

    2. Comparing two variables or values:
      resolvecondition(result, var1 OPERATOR var2);
      The var1 or var2 can be a variables or values. When var1 or var2 is a variable then the content of the variable will be used for comparison. Only when using a 'strict' comparison operator (=== or !==) then var1 and var2 must be variables (or null).

      Available operators:
      ==equal
      !=not equal
      <  or  LTlower than *
      >  or  GTgreater than *
      <=  or  LElower or equal than *
      >=  or  GEgreater or equal than *
      ===strict equal (compare only existent variables)
      !==strict not equal (compare only existent variables)
      * Note - because of xml limitations, the usage of '<' and '>' characters is not possible every time!
Examples
resolvecondition(testresult,     setting == mode1);
resolvecondition(testresult, OR, setting == mode2);
resolvecondition(testresult, OR, setting == mode3);
if(testresult, ...);
delayedcall(delay, actions)
delayedcall(id, delay, actions)
Calls / executes the given actions after a given time.

Parameters:
  • id
    An optional unique id for the delayedcall. This id can be used to stop the delayedcall by calling stopdelayedcall(id).
  • delay
    The number of seconds to wait before executing the actions.
  • actions
    The action commands to execute.
Examples
delayedcall(5.0, hidelogo() );
delayedcall(10, looktohotspot(spot1);loadpano(pano2.xml); );
delayedcall(1, showtext('hello');       );
delayedcall(4, showtext('to the pano'); );
<action name="updatemousepos">
  copy(layer[cursor].x, mouse.x);
  copy(layer[cursor].y, mouse.y);
  delayedcall(0.02, updatemousepos() );
</action>
stopdelayedcall(id)
Stop the delayedcall with the given id.

Parameters:
  • id
    The id of the delayedcall that should be stopped.
Examples
<events name="introimage_events"
        onnewpano="delayedcall(introimage, 5.0, hide_introimage() );"
        onremovepano="stopdelayedcall(introimage);"
        />
for(startactions, condition, nextactions, loopactions)
asyncfor(startactions, condition, nextactions, loopactions)
First the startactions will be called, then the condition checked and when it is true - then the loopactions will be called, then the nextactions and then it starts checking the condition again.
The normal for action will continue with the following actions when the for itself is done. The asyncfor will continue intermediately with the following actions and execute the loopactions once per frame.

Parameters:
  • startactions
    The actions that will be called / executed before the for loop starts.
  • condition
    See the condition at the if() documentation.
  • nextactions
    The actions that will be called / executed after one loop (after the loopaction).
  • loopactions
    The actions that will be repeatedly called / executed as long as the condition is true.
Examples
for(set(i,0), i LT 10, inc(i), trace('i=',i) );.
for(set(i,0), i LT layer.count, inc(i), 
  trace('layer[',i,'].name=',layer[get(i)].name);
);  
loop(condition, loopactions)
asyncloop(condition, loopactions, doneactions*)
As long as the condition is true the loopactions will be called repeatedly.
The normal loop action will continue with the following actions when the loop itself is done. The asyncloop will continue intermediately with the following actions and execute the loopactions once per frame. When the async looping is finally done, then the doneactions will be called.

Parameters:
  • condition
    See the condition at the if() documentation.
  • loopactions
    The actions that will be repeatedly called / executed as long as the condition is true.
  • doneactions (optionally, asyncloop only)
    The actions that will be called when the condition becomes false and the looping stops.
Examples
ondown="asyncloop(pressed, layer[scrollarea].scrollby(+2,0) );"
onover="asyncloop(hovering, updatemousepos(), hideinfo() );"
asyncloop(true, framehandler() );
switch(variable)
switch(variable, value1, value2, ...)
The switch action switches the value of the given variable between / through several states. Everytime when the switch action will be called the value will be switched / changed.
When only the variable itself without value parameters will be given, then the variable will be switched between true and false.
When there are 2 or more values given as parameters then the variable will switch through all of these values.

Parameters:
  • variable
    The variable that should be switched/changed.
  • value1, value2, ... (optionally)
    The switch-through values for this variable.
Examples
switch(fullscreen);
switch(hotspot.visible);
switch(layer[button1].visible);
switch(layer[button1].alpha, 1.0, 0.5);
switch(layer[child].parent, button1, button2, button3);
switch(destpos, -100, 0, +100); tween(y,get(destpos));
push(variable)
pop(variable)
push - saves/pushes the value of the variable to the stack.
pop - restores/pops the value from the stack and saves it into the variable.

The stack is based on the principle of Last In First Out (LIFO).

Parameters:
  • variable
    Any variable.
Examples
push(varA);
push(varB);
pop(varB2);
pop(varA2);
stopall()
  • Stops / breaks all currently running actions / tweens.
  • Remove also all currently queued actions.
breakall()
  • Stops / breaks all currently running actions / tweens.
events.dispatch(eventname)
  • Dispatches the 'eventname' named events from all <events> elements.
Examples
<events name="events1" myevent="trace(events1...);" />
<events name="events2" myevent="trace(events2...);" />
...
events.dispatch(myevent);
add(variable, valueA, valueB*)
sub(variable, valueA, valueB*)
mul(variable, valueA, valueB*)
div(variable, valueA, valueB*)
mod(variable, valueA, valueB*)
pow(variable, valueA, valueB*)
Actions for mathematical calculations.
These actions can be used with 2 or 3 parameters:

  • with 2 parameters:
    • add(dst,val1)  ⇒  dst = dst + val1 (like +=)
    • sub(dst,val1)  ⇒  dst = dst - val1 (like -=)
    • mul(dst,val1)  ⇒  dst = dst * val1 (like *=)
    • div(dst,val1)  ⇒  dst = dst / val1 (like /=)
    • mod(dst,val1)  ⇒  dst = dst % val1 (modulate)
    • pow(dst,val1)  ⇒  dst = dst ^ val1
  • with 3 parameters:
    • add(dst,val1,val2)  ⇒  dst = val1 + val2
    • sub(dst,val1,val2)  ⇒  dst = val1 - val2
    • mul(dst,val1,val2)  ⇒  dst = val1 * val2
    • div(dst,val1,val2)  ⇒  dst = val1 / val2
    • mod(dst,val1,val2)  ⇒  dst = val1 % val2 (modulate)
    • pow(dst,val1,val2)  ⇒  dst = val1 ^ val2

Note - val1/val2 can be values or variables. When val1 or val2 is a variable then automatically the content of the variable will be used!

Parameters:
  • variable
    The variable where the result of the calculation will be stored.
    When the variable doesn't exists it will be created.
  • valueA / valueB (optionally)
    The values or variables for the calculation.
Examples
set(val, 1);
add(val, 1);
trace('val should be 2: val=',val);
mul(doublewidth, width, 2.0);
mul(scale, 0.5);
div(result, vala, valb);
add(dst,rotate,360); tween(rotate,get(dst),5);
add(xpos, mouse.x, mouse_x_offset);
sub(destx, stagewidth,  destwidth);
div(aspect,16,9);
mod(cur_hlookat,cur_hlookat,360);
pow(sqrt,val,0.5);
inc(variable, byvalue*, max*, min*)
dec(variable, byvalue*, min*, max*)
These actions increase or decrease variable (with saturation or limiting).

Parameters:
  • variable
    The variable to increase or decrease.
  • byvalue (optionally)
    Increase or decrease the variable by this value. When not set the variable will be increase or decrease by 1.
  • max / min (optionally)
    Defines maximum and minimum values, when one limit will be reached then the value will be set back to the other limit value. This can be used to let the varibale wrap around a defined range or to clip at at specific limit (with min=max).
Examples
inc(i);
inc(frame,1,get(lastframe),0);
inc(ypos,30);
inc(view.hlookat, 2, 90, 90);
Math.*
The Math object provides constants and actions for mathematical calculations.

The most Math actions can be called in two ways - either by just passing the name of the variable - then variable will be used as parameter and the result of the calculation will be stored back to the variable, or by specifying an additionally parameter where the result should be stored.

roundval(variable, decimalplaces*)
Rounds the value of the variable to given decimal places (0 when not set).
(Note - the variable will be a string internally after rounding)

Parameters:
  • variable
    The variable to be rounded.
  • decimalplaces (optionally)
    The number of decimal places.
Examples
roundval(val);
roundval(val,2);
copy(cur_hlookat,view.hlookat);
mod(cur_hlookat,360);
roundval(cur_hlookat,2);
copy(cur_vlookat,view.vlookat);
roundval(cur_vlookat,2);
txtadd(msg,'looking at ',get(cur_hlookat),'/',get(cur_vlookat));
txtadd(destination, txt1, txt2*, txt3*, ...)
The txtadd action can be used to add/connect several texts / values together.
The action can be used with 2 or more parameters. When using only two parameters (destination and a text) then the text will be added to current value of the destination variable.

Parameters:
  • destination
    The destination variable where the connected text will be stored.
    The variable will be created when it doesn't exists.
  • txt1, txt2, txt3, ... (optionally)
    The texts that will be connected together. When using only one txt parameter then this text will be added to the content of current destination variable.
    Note - when the content of a variable should be used - then the get() action must be used to resolve the variable!
Examples
txtadd(picfilename,'%CURRENTXML%/pic_',get(pic),'.jpg');
txtadd(crop,'0|',get(ypos),'|333|285');
txtadd(pname, 'thumbbar_image_', get(i));
txtadd(layer[text].html,'[p]',get(data[txt1].content),'[/p]');
txtadd(msg,get(view.fovtype),'=',get(fov),'°');
subtxt(dstvar, srcvar, startpos, len)
The subtxt action extracts a part of an other text.

Parameters:
  • dstvar
    The destination variable where the extracted text will be stored.
    The variable will be created when it doesn't exists.
  • srcvar
    The variable or text with the source text.
  • startpos
    The starting position from where the text should be extracted.
  • len
    The length of the text to extract.
indexoftxt(dstvar, txt, searchtxt, startindex*)
The indexoftxt action searches for the index/position from one text inside another text.

Parameters:
  • dstvar
    The destination variable where the extracted text will be stored.
    The variable will be created when it doesn't exists.
  • txt
    The text in which should be searched.
  • searchtxt
    The text that should be searched for.
  • startindex (optionally)
    The starting startindex/position where to start searching the text (0 by default).
txtreplace(var, searchtext, replacetext)
txtreplace(dstvar, srcvar, searchtext, replacetext)
The txtreplace action searches in 'var/srcvar' for all occurrences of 'searchtext' and replaces them with 'replacetext'.

Parameters:
  • var / srcvar / dstvar
    The variable where to search for (var, srcvar) and where the result will be stored (var, dstvar).
    The variable will be created when it doesn't exists.
  • searchtxt
    The text that should be searched for.
  • replacetext
    The text that will replace the 'searchtxt' occurrences.
fromcharcode(var, charcode)
The fromcharcode action converts the given character code to a string and stores in the given variable.

Parameters:
  • var
    The variable where to store the character.
    The variable will be created when it doesn't exists.
  • charcode
    The Unicode character code as number.
escape(var)
escape(var, text)
unescape(var)
unescape(var, text)
The escape and unescape actions are escaping the content of the given variable or the given text and then storing the result in the given variable.

Parameters:
  • var
    Without text parameter - the variable which will be escaped/unescaped.
    With text parameter - the variable where the escaped/unescaped text will be stored.
  • text (optionally)
    The text that that will be escaped/unescaped.
tween(variable, value, time*, tweentype*, donecall*, updatecall*)
The tween action can be used for a time-controlled animation / change of a variable.
The action will dynamically change the current value of the variable to the given value.

Parameters:
  • variable
    The variable that should be changed.

  • value
    The destination value for this variable.
    When tweening percent values - add a '%' character to the value.
    Note - to tween to the value of another variable use the get() action to get the value of the other value!

  • time (optionally)
    • The time in seconds for the change from the current value to the destination value (0.5 seconds by default).
    • Instead of using a fixed time for the change it is possible to define the maximum moving distance for the value and a time for that distance.
      This allows to use a short time for a short distance and long time for a long distance. This can be done by using the distance function:

      distance(maxdistance,maxtime)
      • maxdistance - the maximum distance between the start and the destination value
      • maxtime - the time in seconds for this maximum distance

  • tweentype (optionally)
    The interpolation type (easeOutQuad by default).
    See here for all available tween types: tweentypes.

  • donecall (optionally)
    The action commands to execute when the destination value has been reached.
    Instead of some actions, it is also possible to use the special keyword WAIT - in this case the user interface and the execution of the following actions will be blocked until the destination value has been reached.

  • updatecall (optionally)
    These action will be called every time (=every frame) when the value will be updated / changed! WARNING - use updatecall with care! When heavly used this can reduce the rendering performance!

Some information about the origin of the name "tween" - Wikipedia about Tweening.
Examples
tween(scale,2);
tween(rotate,90);
tween(width,50%);
onover="tween(alpha,0.7,distance(0.3,0.2));"
onout="tween(alpha,1.0,distance(0.3,0.2));"
set(alpha,0);
set(visible,true);
tween(alpha, 1.0 ,0.3);
tween(layer[logo].width, get(destwidth));
set(layer[image].enabled,false);
tween(layer[image].alpha,0.0,0.5,default,removeplugin(image));
set(view.stereographic,true);
tween(view.vlookat, 90.0, 2.0);				
tween(view.fisheye, 1.0, 2.0);
tween(view.fov, 150.0, 2.0);
stoptween(variable, ...)
The stoptween action stops a currently running tween action.

Parameters:
  • variable
    The name of the variable which is currently tweening and should be stopped.
  • ... variable, variable, ... (optionally)
    Addtional variables that should stop tweening.
Examples
ondown="tween(layer[text].y, 10, distance(400,0.7), linear);"
onup="stoptween(layer[text].y);"
Here all supported tween types for the tween action.
Linear Ease:
  • linear
Ease Out:
  • easeOutQuad (the default)
  • easeOutQuart
  • easeOutQuint
  • easeOutSine
  • easeOutBounce
  • easeOutCirc
  • easeOutCubic
  • easeOutExpo
Ease In:
  • easeInQuad
  • easeInQuart
  • easeInQuint
  • easeInSine
  • easeInBounce
  • easeInCirc
  • easeInCubic
  • easeInExpo
Ease Out and In:
  • easeOutInQuad
  • easeOutInQuart  *
  • easeOutInQuint  *
  • easeOutInSine  *
  • easeOutInBounce  *
  • easeOutInCirc  *
  • easeOutInCubic  *
  • easeOutInExpo  *
Ease In and Out:
  • easeInOutQuad  *
  • easeInOutQuart  *
  • easeInOutQuint  *
  • easeInOutSine  *
  • easeInOutBounce  *
  • easeInOutCirc  *
  • easeInOutCubic  *
  • easeInOutExpo  *

Here some online visualization of the different tween types:
http://hosted.zeh.com.br/tweener/docs/en-us/misc/transitions.html
http://hosted.zeh.com.br/mctween/animationtypes.html

* only via moretweentypes plugin
These tween types are only available when including the moretweentypes plugin.
loadpano(xmlpath, vars*, flags*, blend*)
loadxml(xmlstring, vars*, flags*, blend*)
loadscene(scenename, vars*, flags*, blend*)
Actions to load a new panos.

Note - only the layer, plugin, hotspot, event and lensflare elements with keep="true" will be kept when loading new panos!

Parameters:
  • xmlpath (for loadpano)
    The path/url of the new pano xml file to be loaded (use null for none).
    When a relative path will be used then the file will be loaded from the basedir folder, which is %FIRSTXML% by default. That means that the paths in all loadpano calls are relative to the first loaded xml file.

  • xmlstring (for loadxml)
    The content of a xml file as string/text to be loaded (should be escape-coded).

  • scenename (for loadscene)
    The name of the <scene> to be loaded.

  • vars (optionally)
    Variables to set (use null for none).
    These variables will be set after parsing/resolving the xml but before starting to load the pano images. This can be used to overwrite any settings from the xml or to set addtional ones. The variables can be defined as var1=val1 pairs separated by a & character (e.g. sphere=image.jpg&view.fov=120&view.fisheye=0.35).
    HTML5 Notes - for HTML5 compatibility &amp; instead of & should be used.

  • flags (optionally)
    Addtional flags for loading (use null for none).
    Flags can be combined by a | character.

    Possible flags:
    • MERGE (the recommended flag)
      • Merges all settings from the current and the next pano.
      • If there are plugins and hotspots in the new panorama with the same name as the kept ones, the new elements will not be loaded.
      • This is the recommended setting for virtual tours.
    • KEEPVIEW - keep current view settings
    • KEEPSCENES - keep current scenes (loadpano only)
    • 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
    • KEEPBASE - a predefined combination of:
      KEEPDISPLAY | KEEPCONTROL | KEEPPLUGINS | KEEPPROGRESS
    • KEEPALL - a predefined combination of:
      KEEPVIEW | KEEPDISPLAY | KEEPCONTROL | KEEPPLUGINS | KEEPPROGRESS
    • REMOVESCENES - remove all currently defined scene elements (the same like - set(scene.count,0); )
    • IGNOREKEEP - ignore the keep flags and remove also the elements with keep="true"

  • blend (optionally)
    Blend / fade to next panoroma.

    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 (Flash only)
Examples
loadpano(pano2.xml);
loadpano(pano2.xml, null, MERGE, BLEND(1));
loadscene(scene1);
loadscene(scene1, null, MERGE, BLEND(1));
loadxml('<krpano><image><sphere url="pano.jpg"/></image></krpano>');
loadxml(get(data[xml].content), null, KEEPALL);
loadpano('%SWFPATH%/pano.xml', null, MERGE, BLEND(2));
loadpano(sphere.xml, image.hfov=1.0&view.limitview=fullrange);
openurl(url, target*)
Open an url / link.

Flashplayer Notes - this action requires the External Interface of the Flashplayer!
That means that the action will work offline/locally only when the security settings of the Flashplayer were adjusted. For more details see here - Local / Offline Usage.


Parameters:
  • url
    The url to open.
  • target (optionally)
    The target where the url should be opened.

    Possible settings:
    • _blank - open the url in a new window (the default)
    • _self - open the url in the current frame in the current window
    • _parent - open the url in the parent of the current frame
    • _top - open the url in the top-level frame in the current window
Examples
openurl('http://krpano.com',_self);
openurl('help.html');
lookat(atH, atV, fov*)
Look at this panorama position.

Parameters:
  • atH
    Horizontal position in degrees, spherical coordinates (-180 to +180).
  • atV
    Vertical position in degrees, spherical coordinates (-90 to +90).
  • fov (optionally)
    The new field of view in degrees (0 - 179).
Examples
lookat(0,0);
lookat(0,0,90);
loadpano(pano.xml);
lookat(45.1, -20.2, 110.0);
lookto(toH,toV,fov*,motiontype*,shortestway*,nonblocking*,donecall*)
looktohotspot(hotspotname*, fov*, motiontype*, shortestway*)
moveto(toH, toV, motiontype*)
zoomto(fov, motiontype*)
Move the view from current looking position to the given position.

Note - the user interface and all other actions are blocked during the movement. That means the next action will be executed when the current action was done. The oninterrupt action can be used to make these actions interrupt able by the user.

Parameters:
  • toH
    Horizontal destination looking direction (-180 to +180, wraparound possible).

  • toV
    Vertical destination looking direction (-90 to +90).

  • hotspotname (for looktohotspot, optionally)
    The name of the hotspot. Use the hotspot position (ath/atv) as destination position.
    When no name will be defined and looktohotspot() will be called from a hotspot event then the caller hotspot itself will be used.

  • fov (optionally)
    The destination fov (0 to 179).
    The looktohotspot action will use automatically the size of the hotspot as destination fov when the fov was not set. The other actions keep the current fov when not set.

  • motiontype (optionally)
    The type of the motion.

    Possible settings:
    • linear(speed) - a linear motion
      • 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)
    • tween(tweentype,time) - tween animation curve
      • tweentype = one of the tween types
      • time = time in seconds for the movement

  • shortestway (optionally)
    The use the shortest possible way from the current to the destination position.
    Possible settings: true or false (default=true).

  • nonblocking (optionally, lookto only)
    When set to true, then the lookto action will not wait for completing the movement before continue executing the the following actions. The user-interface will also be not blocked.
    When the lookto movement is done then the donecall action will be called (when defined).

  • donecall (optionally, lookto only, only when nonblocking is true)
    This action will be called when the nonblocking lookto movement is done.
Examples
moveto(100.0,5,linear(10));
zoomto(130,smooth());
lookto(33,-22,30,smooth(100,50,20));
looktohotspot(hotspot1);
looktohotspot(hotspot2, 40);
looktohotspot(hotspot3, 25, smooth(100,50,20));
looktohotspot(get(name));
adjusthlookat(desthlookat)
Adjusts the view.hlookat value for manual tweening.
It fixes the 360 wrap around for the shortest way to desthlookat.

Parameters:
  • desthlookat
    The intended destination hlookat value. The current view.hlookat variable will be adjusted (without changing the current view) to be next to this value.
Examples
adjusthlookat(140);
tween(view.hlookat, 140);
getlooktodistance(result, toH, toV, fromH*, fromV*)
Get the spherical distance between the fromH / fromV and toH / toV lookto points (in degrees). The result will be always between 0.0 and 180.0 (more than 180 degree distance is not possible on a sphere).

Parameters:
  • result
    The name of the variable where the distance value will be stored.
    The variable will be created when it doesn't exists.
  • toH
    Horizontal looking-to position (-180 to +180, wraparound possible).
    Can be a variable name or a value.
  • toV
    Vertical looking-to position (-90 to +90).
    Can be a variable name or a value.
  • fromH (optionally)
    Horizontal looking-from position (-180 to +180, wraparound possible).
    Can be a variable name or a value.
    When not defined, the current horizontal looking direction (view.hlookat) will be used by default.
  • fromV (optionally)
    Vertical looking-from position (-90 to +90).
    Can be a variable name or a value.
    When not defined, the current vertical looking direction (view.vlookat) will be used by default.
stoplookto()
Stop a non-blocking lookto / looktohotspot / moveto / zoomto action.

stopmovements()
Instantly stop all user-driven (by mouse, keyboard or touch) panning and zooming movements.

wait(parameter)
Wait a number of seconds or wait for an event.

Note - The user interface and all other actions are blocked during the waiting. That means the next action will be executed when the current action was done. The oninterrupt action can be used to make this action interrupt able by the user.

Parameters:
  • parameter
    • any number - this the time the action will wait in seconds
    • LOAD - wait until loading is finished
    • BLEND - wait until loading and blending are finished
Examples
oninterrupt(break);
lookto(150,30,70);
wait(3);
lookto(242,0,150);
lookto(280,-10,50);
wait(3);
loadpano(pano2.xml,null,MERGE,BLEND(2));
lookat(100,50,5);
wait(BLEND);
lookto(100,50,150);
oninterrupt(actions)
This action can be used before starting a set of actions (like lookto, looktohotspot, moveto, zoomto, wait and tween with WAIT as donecall) that are blocking the user interface.
When any of these actions will be interrupted by the user (e.g. by a click) then the these actions will be stopped and the in the oninterrupt action defined actions be executed.

Parameters:
  • actions
    • The action commands to call on a user interrupt.
    • Addtionally there is a special command possible here:
      break - this will just break the current actions.
Examples
oninterrupt(break);
lookto(150,30,70);
wait(3);
lookto(242,0,150);
lookto(280,-10,50);
wait(3);
oninterrupt( trace(user interrupt); );
lookto(0,0,90);			
lookto(90,0,90);
lookto(180,0,90);
lookto(270,0,90);
lookto(0,0,90);
screentosphere(x,y,h,v)
spheretoscreen(h,v,x,y)
Actions for converting between screen and spherical coordinates.
All parameters must be variables, using values is not possible!

The screentosphere action will convert the x/y variables to the h/v variables and the spheretoscreen action the h/v variables to the x/y variables.

Parameters:
  • x / y
    Variables with screen coordniates in the pixels from the left top edge.
    spheretoscreen: When the variables doesn't exist they will be created.
  • h / v
    Variables with spherical coordniates in the degrees (360x180).
    screentosphere: When the variables doesn't exist they will be created.
Examples
screentosphere(mouse.x, mouse.y, toh, tov);
remapfovtype(fov, srcfovtype, dstfovtype)
remapfovtype(fov, srcfovtype, dstfovtype, width, height)
Remap a fov value from one fovtype to another.

When changing the viewing fovtype and at the same time, remapping the viewing fov, then the resulting pano zoom will keep the same.

Parameters:
  • fov
    A variable with the fov value that should be changed.
    The result will be stored in the same variable.
  • srcfovtype
    The current fovtype.
    Can be: HFOV, VFOV, DFOV or MFOV.
  • dstfovtype
    The new fovtype.
    Can be: HFOV, VFOV, DFOV or MFOV.
  • width (optionally)
    The width of the fov area/frame in pixels.
    By default the current screen/area size will be used.
  • height (optionally)
    The height of the fov area/frame in pixels.
    By default the current screen/area size will be used.
Examples
set(view.fovtype, HFOV);
set(view.fov, 90);
...
set(view.fovtype, VFOV);
remapfovtype(view.fov, HFOV, VFOV);
showtext(text, textstyle*)
Show a text message on the screen (Flash only).

Note - only one text can be shown at one time! When calling showtext again the current shown text will be removed!

Parameters:
  • text
    • The text to show.
    • HTML tags can be used to format the text.
    • Using < and > characters will be not possible (because of xml limitations).
    • The [ and ] characters can be used instead - krpano will map them automatically.
    • To get the real [ and ] characters use them twice - [[ and ]].

    Examples for formating:
    • [b]bold[/b]bold text
    • [i]italic[/i]italic text
    • [u]underline[/u]underlined text
    • [br] ⇒ line break

  • textstyle (optionally)
    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
updateobject(updateall*, updatefov*)
Updates / rebuilds the internal 3D model of the pano object.
This must be called after changes of the display.details and display.tessmode settings.
When changing of the image.hfov, image.vfov or image.voffset settings interactivly, this action must be called with updatefov=true to get an updated pano object!

Note - the rebuilding of the internal 3D model is a heavy process! This action should be used carefully!

Parameters:
  • updateall (optionally)
    For multi-resolution pano - should all levels be updated?
    Possible settings: true or false (default=false).
  • updatefov (optionally)
    Reparse the image.hfov, image.vfov and image.voffset settings when building the pano object.
    Possible settings: true or false (default=false).
Examples
set(image.hfov,1);
updateobject(true,true);
updatescreen()
  • Force a redraw of the panorama view.
  • The rendering quality will not change.
invalidatescreen()
addlayer(name)
addplugin(name)
addhotspot(name)
addlensflare(name, ath*, atv*)
Dynamically create and add a new layer, plugin, hotspot or lensflare element.

Parameters:
  • name
    Name of the new layer/plugin, hotspot or lensflare element.
  • ath / atv (lensflare only)
    Horizontal and vertical position in degrees for the lensflare element.
Examples
addlayer(button);
set(layer[button].url,button.jpg);
set(layer[button].align,bottom);
set(layer[button].x,10);
set(layer[button].y,20);
set(layer[button].onhover,showtext('hovering the new button'));
set(layer[button].onclick, removelayer(button) );
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].onclick, removehotspot(newspot) );
addhotspot(polyspot);
set(hotspot[polyspot].fillalpha, 0.25);
set(hotspot[polyspot].borderalpha, 0.50);
set(hotspot[polyspot].onclick, removehotspot(polyspot) );
set(hotspot[polyspot].point[0].ath,-10);
set(hotspot[polyspot].point[0].atv,-10);
set(hotspot[polyspot].point[1].ath,-10);
set(hotspot[polyspot].point[1].atv,+10);
set(hotspot[polyspot].point[2].ath,+10);
set(hotspot[polyspot].point[2].atv,+10);
set(hotspot[polyspot].point[3].ath,+10);
set(hotspot[polyspot].point[3].atv,-10);
addlensflare(sun, 20, -60);
set(lensflare[sun].set,  FLARESET2);
set(lensflare[sun].size, 0.7);
removelayer(name)
removeplugin(name)
removehotspot(name)
removelensflare(name)
Dynamically remove and destroy a layer, plugin, hotspot or lensflare element.

Parameters:
  • name
    Name of the layer/plugin, hotspot or lensflare element that should be removed.
js( ...Javascript code... )
Execute Javascript code.

Flashplayer Notes - this action requires the External Interface of the Flashplayer! This means the action will work offline/locally only when the security settings of the Flashplayer were adjusted. See here for more detatils - Local / Offline Usage.
Examples
Code in the HTML or JS file:
function test(p1, p2, p3)
{
  alert(p1 +" hlookat=" + p2 + " vlookat=" + p3);
}
Code in the XML file:
onclick="js( test('Hello', get(view.hlookat), get(view.vlookat)) );"
fscommand(...)
The fscommand action can be used to control the standalone Flashplayer.

Use:
  • fscommand(quit)
    Quit the standalone flashplayer.
  • fscommand(showmenu,false)
    Hide the menubar of the standalone flashplayer (Windows only).
  • fscommand(exec,'application.exe')
    Start an external application.
    The 'application.exe' must be in a subfolder named "fscommand".
showlog(state*)
Show or hide the trace output log.

Parameters:
  • state (optionally)
    • true to show the log (default)
    • false to hide the log
trace(...)
Traces texts or the content of variables to the output log.

Note - many traces can affect the rendering performance!

Parameters:
  • ....
    Any text or variables. When passing a variable then automatically the content of the variable will be used.
Examples
trace('view.maxpixelzoom=', view.maxpixelzoom);
<events onkeydown="trace('keycode=',keycode);" />
onresize="trace('size=',stagewidth,'x',stageheight);"
onclick="trace('mouse clicked at ', mouse.x, ' / ', mouse.y);"
trace('xyz=',xyz,' get(xyz)=',get(xyz));
error(errormessage)
Show a fatal error message and stops panorama viewing.

Parameters:
  • errormessage
    The error message to show.