close panorama

Documentation

 

krpano Plugin Interface for version 1.0.8.14
Select Version:

krpano provides a small and simple interface for developing own plugins. A plugin can be either a 'code-only' plugin that extends krpano with additional functionality or controls krpano and / or it can be a 'graphical-plugin' which shows or does something on the screen.

There are two types of plugins: The basic plugin-to-krpano and krpano-to-plugin interfaces are almost the same for Flash plugins and for HTML5/Javascript plugins, only system and language specific code is different.

The basic structure is that the plugin has these public functions, which will be called from krpano:
  • A registerplugin function - this function will be called from krpano when the plugin will be loaded. The function provides a krpano interface object and the krpano plugin object itself.
  • An unloadplugin function - when the plugin will be removed from krpano, then this function will be called. Here all elements and events that the plugin has added should be removed.
  • And optionally an onresize function to allow the plugin reacting on size changes of the plugin element.
The plugin itself can add custom functions or attributes to krpano just by adding / setting them directly to the krpano object or to the plugin object. For custom attributes that can be set from the xml there is additionally the registerattribute function - it allows adding an attribute with a default value while keeping the value from the xml. And the registerattribute function can be used to add setter/getter attributes - this are attributes which will cause automatically calling a get or set function when accessing the variable - this can be used to get notified when an attribute will been changed.

Actionscript3 Flash plugins

Flash plugins for the krpano Flash viewer can be build either with the free mxmlc compiler from the Flex SDK (recommended) or with Flash Professional CS.
Here two examples / templates of the basic code structure for a krpano Flash plugin:
Flex SDK mxmlc code (.as) Flash CS code (.fla) 
download plugintemplate.as/*  
    krpano as3 plugin example / template
    for mxmlc (.as)
*/

package
{
    import flash.display.*;
    import flash.text.*;
    import flash.events.*;
    import flash.utils.*;
    import flash.system.*;
    
    [SWF(width="400", height="300", backgroundColor="#000000")]
    public class plugintemplate extends Sprite
    {
        public var krpano : Object = null;
        public var plugin : Object = null;
        
        public function plugintemplate()
        {
            if (stage == null)
            {
                // startup when loaded inside krpano
                this.addEventListener(Event.ADDED_TO_STAGE, versioncheck);
            }
            else
            {
                // direct startup - show plugin version info
                stage.scaleMode = "noScale";
                stage.align = "TL";

                var txt:TextField = new TextField();
                txt.defaultTextFormat = new TextFormat("_sans",14,0xFFFFFF,false,false,false,null,null,"center");
                txt.autoSize = "center";
                txt.htmlText = "krpano\n\nplugintemplate plugin";
                addChild(txt);

                var resizefu:Function = function(event:Event=null):void
                {
                    txt.x = (stage.stageWidth  - txt.width )/2;
                    txt.y = (stage.stageHeight - txt.height)/2;
                }

                stage.addEventListener(Event.RESIZE, resizefu);

                resizefu(); 
            }
        }

        private function versioncheck(evt:Event):void
        {
            // compatibility check of the krpano version by using the old plugin interface:
            // - the "version" must be at least "1.0.8.14"
            // - and the "build" must be "2011-05-10" or greater
            this.removeEventListener(Event.ADDED_TO_STAGE, versioncheck);
            
            var oldkrpanointerface:Object = (getDefinitionByName("krpano_as3_interface") as Class)["getInstance"]();
            
            if (oldkrpanointerface.get("version") < "1.0.8.14" || oldkrpanointerface.get("build") < "2011-05-10") 
            {
                oldkrpanointerface.trace(3, "plugintemplate plugin - too old krpano viewer version (min. 1.0.8.14)");
            }
        }
        
        // registerplugin
        // - the start for the plugin
        // - this function will be called from krpano when the plugin will be loaded
        public function registerplugin(krpanointerface:Object, pluginfullpath:String, pluginobject:Object):void
        {
            // get the krpano interface and the plugin object
            krpano = krpanointerface;
            plugin = pluginobject;
            
            // add plugin attributes and functions
            // some example attributes:
            plugin.registerattribute("attr1", "defaultvalue");
            plugin.registerattribute("attr2", 123.456);
            plugin.registerattribute("attr3", false);
            plugin.registerattribute("attr4", 10, attr4_setter, attr4_getter);
            // add a from xml callable functions:
            plugin.testfunction1 = testfunction1;
            plugin.testfunction2 = testfunction2;
            plugin.testfunction3 = testfunction3;
            
            // say hello
            krpano.trace(1,"hello from plugin[" + plugin.name + "]");
            
            // add plugin graphic content / child objects (optionally)
            if(0) // 'if(0)' means that this code will not be executed, the code here is only an example for how-to add addtional graphical content!
            {
                // register the size of the plugin content (optionally)
                // e.g. to set the plugin source size to 256x256 pixels:
                plugin.registercontentsize(256,256);

                // the plugin itself is already a Flash Sprite Object, 
                // so to add addtional Flash DisplayObjects
                // just add them to the plugin itself:
                var exampleChildSprite:Sprite = new Sprite();
                this.addChild(exampleChildSprite);
            }
        }

        // unloadplugin
        // - the end for the plugin
        // - this function will be called from krpano when the plugin will be removed
        public function unloadplugin():void
        {
            // remove all your custom plugin stuff here 
            // ...

            plugin = null;
            krpano = null;
        }
        
        // onresize (optionally)
        // - this function will be called from krpano when the plugin will be resized
        // - can be used to resize sub elements manually
        // return:
        // - return true to let krpano scale the plugin automatically
        // - return false to disable any automatic scaling
        public function onresize(width:int, height:int):Boolean
        {
            // ...
            
            return false;   // don't do any automatically scaling
        }
        
        
        // example setter/getter function and plugin functions:
        private var attr4:Number = 10.0;

        private function attr4_setter(newvalue:Number):void
        {
            krpano.trace(1,"attr4 will be changed from " + attr4 + " to " + newvalue);
            attr4 = newvalue;
        }
        
        private function attr4_getter():Number
        {
            return attr4;
        }
        
        private function testfunction1(...rest):void
        {
            // trace the given arguments
            krpano.trace(1,"testfunction1() called with " + rest.length + " arguments:");
            for (var i:int=0; i<rest.length; i++)
                krpano.trace(1,"argument" + (i+1) + "=" + rest[i]);

            // trace the current viewing direction and fov                
            krpano.trace(1,"current view:");
            krpano.trace(1,"hlookat = " + krpano.view.hlookat);
            krpano.trace(1,"vlookat = " + krpano.view.vlookat);
            krpano.trace(1,"fov = " + krpano.view.fov);
        }
        
        private function testfunction2(...rest):void
        {
            // change the current fov to 120
            krpano.view.fov = 120.0;
        }
        
        private function testfunction3(...rest):void
        {
            // call krpano actions
            krpano.call("lookto(0,0,90); wait(2); lookto(90,0,90);");
        }
    }
}

Javascript HTML5 plugins

The krpano Javascript plugins are just plain Javascript code. Special tools for compiling or building are not necessary, but to reduce the filesize of the final plugin file compressing or minimizing the Javascript code is recommended.
Here an example / template of the basic code structure for a krpano Javascript plugin:
download plugintemplate.js/*
    krpanoJS javascript plugin example / template
*/

var krpanoplugin = function()
{
    var local = this;   // save the 'this' pointer from the current plugin object

    var krpano = null;  // the krpano and plugin interface objects
    var plugin = null;

    var plugincanvas = null;        // optionally - a canvas object for graphic content
    var plugincanvascontext = null;


    // registerplugin - startup point for the plugin (required)
    // - krpanointerface = krpano interface object
    // - pluginpath = string with the krpano path of the plugin (e.g. "plugin[pluginname]")
    // - pluginobject = the plugin object itself (the same as: pluginobject = krpano.get(pluginpath) )
    local.registerplugin = function(krpanointerface, pluginpath, pluginobject)
    {
        krpano = krpanointerface;
        plugin = pluginobject;

        // add plugin attributes and functions
        // some example attributes:
        plugin.registerattribute("attr1", "defaultvalue");
        plugin.registerattribute("attr2", 123.456);
        plugin.registerattribute("attr3", false);
        plugin.registerattribute("attr4", 10, attr4_setter, attr4_getter);
        // add a from xml callable functions:
        plugin.testfunction1 = testfunction1;
        plugin.testfunction2 = testfunction2;
        plugin.testfunction3 = testfunction3;

        // say hello
        krpano.trace(1,"hello from plugin[" + plugin.name + "]");

        // add plugin graphic content (optionally)
        var havegraphiccontent = false;
        if (havegraphiccontent) // this code here is only an example for how-to add addtional graphical content!
        {
            // register the size of the plugin content
            // e.g. to set the plugin source size to 256x256 pixels:
            plugin.registercontentsize(256,256);

            plugincanvas = document.createElement("canvas");
            plugincanvas.width  = 256;
            plugincanvas.height = 256;
            plugincanvas.style.width  = "100%";  // automatic scale with parent
            plugincanvas.style.height = "100%";
            plugincanvas.onselectstart = function() { return false; };  // fix select mouse cursor

            // the plugin "sprite" variable holds the visible html element
            // - it can be used to add elements or events
            plugin.sprite.appendChild(plugincanvas);

            // draw something on the canvas
            // ...
        }
    }

    // unloadplugin - end point for the plugin (optionally)
    // - will be called from krpano when the plugin will be removed
    // - everything that was added by the plugin (objects,intervals,...) should be removed here
    local.unloadplugin = function()
    {
        plugin = null;
        krpano = null;
    }

    // hittest - test for clicks on the plugin (optionally)
    // - when the plugin has a graphical irregular shape then it's possible to check here for mouse clicks on it
    // - the typical usage is to check for a hit on the canvas element
    local.hittest = function(x,y)
    {
        if (plugincanvascontext)
        {
            return plugincanvascontext.isPointInPath(x,y);
        }

        return false;
    }

    // onresize - the plugin was resized from xml krpano (optionally)
    // - width,height = the new size for the plugin
    // - when not defined then only the parent html element will be scaled
    local.onresize = function(width,height)
    {
        // not used in this example

        return false;
    }


    // private plugin functions:

    // example setter/getter function and plugin functions:
    var attr4 = 10.0;

    function attr4_setter(newvalue)
    {
        krpano.trace(1,"attr4 will be changed from " + attr4 + " to " + newvalue);
        attr4 = newvalue;
    }

    function attr4_getter()
    {
        return attr4;
    }

    function testfunction1()
    {
        // trace the given arguments
        krpano.trace(1,"testfunction1() called with " + arguments.length + " arguments:");
        for (var i=0; i<arguments.length; i++)
            krpano.trace(1,"argument" + (i+1) + "=" + arguments[i]);

        // trace the current viewing direction and fov
        krpano.trace(1,"current view:");
        krpano.trace(1,"hlookat = " + krpano.view.hlookat);
        krpano.trace(1,"vlookat = " + krpano.view.vlookat);
        krpano.trace(1,"fov = " + krpano.view.fov);
    }

    function testfunction2()
    {
        // change the current fov to 120
        krpano.view.fov = 120.0;
    }

    function testfunction3()
    {
        // call krpano actions
        krpano.call("lookto(0,0,90); wait(2); lookto(90,0,90);");
    }
};

Compress / Minimize the Javascript Plugin Code

This step or part is optionally, but to reduce the filesize of the plugin, compressing or mimizing the Javascript file is recommended. Good tools for that are the Google Closure Compiler, the YUI Compressor or other similar tools.

Both of the above tools can be used offline, but there are also online tools available:

The krpano Plugin Interface

These are the interface functions of the plugin that will be called from krpano. In Flash/Actionscript these functions must be public functions of the startup Flash object.
And in Javascript these functions must be members of a globally defined object named 'krpanoplugin'.
  • registerplugin(krpanointerface, pluginpath, pluginobject)
    • The registerplugin() function will be called when the plugin was loaded into krpano and is ready for usage.
    • Here the plugin can add / register attributes, functions, add graphical content to the plugin or to the viewer and do many things more.
    • Parameters that will be passed with the registerplugin() function:
      • krpanointerface
        The krpanointerface Object - this is an object which provides access to interface functions and to the whole krpano data structure.
      • pluginpath
        A String with the 'full path' to the plugin object, e.g. "plugin[name]".
      • pluginobject
        The internal krpano plugin object. This object provides direct access to all plugin attributes and functions.
  • unloadplugin()
    • The unloadplugin() function will be called from krpano when plugin will be removed.
    • Here the plugin should remove all content that it has added (e.g. graphical objects, event listeners, timers, ...).
  • onresize(width, height) (optionally)
    • The onresize() function will be called when the plugin will be resized.
    • The parameters width and height are the new size in pixels.
    • Here the plugin can adjust or resize own graphical content.
    • The onresize() function can optionally return a Boolean value - when it returns true then krpano will try to scale the plugin automatically, when false will be returned then krpano will not scale the plugin.
  • hittest(x, y) Javascript only
    • The hittest() is optionally and will be only called in the krpanoJS viewer.
    • This function has the mouse x/y coordinates (mapped to the plugin) as parameters.
    • The plugin should check if that coordinates hit the plugin object.
    • This is only necessary when the plugin has an irregular graphical shape.
    • The typical usage would be to check the surface of a canvas object.

The 'krpanointerface' Object

The krpanointerface object (in the examples above used as 'krpano' variable) will be passed to the plugin in its registerplugin() function. This is object is the direct interface to krpano. It provides direct access to the whole krpano structure and functions. All mapped xml nodes, arrays, objects and attributes can be accessed directly with it. Additionally it provides some functions for data access, action-code calling/executing and more - see below.
Functions of the 'krpanointerface' Object: (case-sensitive)
  • set(variable, value)
    • Sets a variable to a given value.
    • When the variable or the path to it, don't exist then the variable and path will be created.
    • Works like the xml set() action.
  • get(variable)
    • Returns the value of a variable.
    • Returns 'null' when the variable doesn't exist.
  • call(actionscode, callerobject*, insertbefore*)
    • Add action code to the krpano actions/command queue. When the queue is currently not blocked by an other action, then the given actions will be directly executed.
    • actionscode = a String with one or more krpano actions.
    • callerobject (optionally) = the Object that was calling the actions (e.g. the pluginobject itself). This allowes direct access to the object attributes in the actions code, e.g. just set(x,1) instead of set(plugin[name].x,1).
    • insertbefore (optionally) = insert the given actions before all other actions to the actions/command queue (true) or insert it at the end (false, default).
  • trace(code, message)
    • Trace out messages to the krpano log.
    • code = numeric code of the message-type:
      • 0 = DEBUG message - will be only shown with enabled debugmode
      • 1 = INFO message
      • 2 = WARNING message
      • 3 = ERROR message - will also open the log automatically.
      • 4 = FATAL ERROR - this message will be shown in the middle of the viewer.
  • parsePath(path)
    • Resolves the krpano placeholders in the given path string.
    • Return value: the resolved path string.
  • loadFile(file, donecallback, errorcallback*)
    loadImage(file, donecallback, errorcallback*) Flash only
    • loadFile() - request to load a file as ByteArray in Flash (any filetype possible) or as String in Javascript (only text/xml files possible).
    • loadImage() - request to load a file as Flash Loader Object (only image/flash files).
    • Additional to normal files these functions also allow to load embedded and encrypted files. They will be decrypted automatically during loading.
    • donecallback and errorcallback - these functions will be called when the loading was successfully or has failed. The usage of the errorcallback is optionally.
      Both functions will be called with an Object as parameter, this object has these attributes:
      • rqurl
        The request url that was used on the loadFile / loadImage call.
      • url
        The full url of the file - parsed and resolved.
      • data
        For Flash Plugins: The loaded file as ByteArray.
        For Javascript Plugins: The loaded file as String.
      • loader
        The Flash Loader Object of the loaded image (loadImage only).
      • errmsg
        A boolean flag with the default value 'true' that indicates if krpano should show an automatic loading error message. Only for usage in the errorcallback function! Set it to 'false' to disable the default loading error message.

The krpano 'Base' Object (the 'base-class' or 'super-class' in programming language)

All krpano mapped-xml-nodes, objects or array-elements and also the krpanointerface-object are derived from a krpano 'Base' object. The 'base' object has some basic functions for adding / registering new attributes and for creating sub array structures.
Functions of the 'Base' Object: (case-sensitive)
  • registerattribute(attributename, defaultvalue, setter*, getter*)
    • Adds a new attribute to the object and sets it the given default value. When the object already has that attribute (e.g. from xml) then the current value will be kept but the type of the attribute will be converted to the type of the default value. The automatic type conversion will work for 'Number' and 'Boolean' datatypes.
      For example: When the attribute was set in the xml file to "123" then the type of the attribute is a 'String', but when registering that attribute with a 'Number' default value, then the attribute will be also converted to 'Number' with the Value 123.
      Setter / Getter (optionally)
      Optionally it's possible to use setter and getter functions instead of a normal attribute. In this case when the attribute will be set from xml or via the set interface then the setter function with the new value will be called, and when the value of the attribute will be read then the getter function will be called to return the value (Note - the setter/getter functions will need to store the value anywhere in this case).

      Accessing the setter/getters from Actionscript or from Javascript:
      • In Actionscript the setter/getter are special objects. Accessing them direct like normal variables/attributes is not possible because the Actionscript language doesn't have/support dynamic setter/getters. For accessing the value these objects have a set(value) function for setting the new value and a get() function for getting the value.
      • In Javascript the setter/getter behave as normal attributes. They can be used directly like normal variables/attributes.

      Notes about setter / getters:
      • Setter and getters are a very powerful instrument for building data structures.
      • They can be used to get informed anytime when the value of an attribute will be changed / updated.
      • With them it possible to check and if necessary correct the value on setting.
      • And/or to set flags and call other functions when the value will be changed.
  • removeattribute(attributename)
    • Removes an attribute from the current object.
  • getattributes()
    • Get all current attributes of the object.
    • Returns a Flash/Javascript 'Array' with the names of all attributes.
  • createobject(objectname)
    • Create a new krpano Base Object inside / under the current object.
    • Returns the new created krpano Base Object.
    • If the object already exists then the exiting object will be kept and returned.
  • removeobject(objectname)
    • Removes an object from the current object.
  • createarray(arrayname)
    • Create a new krpano Array inside the current object.
    • Returns the new created krpano Array Object.
    • If the array exists already then the current Array will be kept and the exiting Array will be returned.
  • removearray(arrayname)
    • Removes and destroys a krpano Array object.

The krpano 'Array' and 'Array-Item' Objects

Arrays in krpano are internally special objects, not native Javascript or Actionscript Arrays. An array will be automatically created when a node in the xml has a 'name' attribute or when a variable with a 'array path' like 'arrayname[itenname].variable' will be set.
The items of the arrays are derived from krpano 'Base' objects and have additional attributes for name and index. Beside of that, these objects can store any kind of attributes or functions, also additional krpano arrays.
Attributes of the krpano 'Array' Objects:
  • count
    • The number of elements in the array.
    • Can be changed dynamically, but only decreasing makes sense, e.g. set it to 0 to remove all items.
Functions of the krpano 'Array' Objects:
  • createItem(name or index)
    • Create a new item inside the array.
    • Returns the new created array item object.
  • getItem(name or index)
    • Get an existing array item.
    • Returns the array item object or null when the items doesn't exist.
  • renameItem(oldname:String, newname:String)
    • Changes the name of an existing item.
  • removeItem(name or index) / removearrayitem(name or index)
    • Removes an item from the array.
    • The removeItem() function returns the removed item object.
    • The removearrayitem() function is the same like the removeItem() function but without return value and also callable from XML / krpano Actions.
  • getArray()
    • Returns a native Actionscript/Javascript linear 'Array' of all array items.
    • Can be used for fast and direct access.
    • The array item can be changed but Array itself should not be changed!

Default Attributes of the krpano 'Array-Item' Objects:
  • name
    • The name of the current array item (read-only).
    • This name can be used for direct access to the array item.
  • index
    • The 0-based index of the current array item (read-only).