Access Keys:
Skip to content (Access Key - 0)

Plugin Development Guide

Presentation

KapInspect is based on a plugin architecture for the various inspectors.

The inspectors provided with KapInspect are compiled in the libraries provided, and it is also possible to create new inspectors through development of a simple module.

You will refer to the provided plugin example, that takes snapshots of the application (not very usefull anyhow)

How to develop a new plugin

  1. Create a Flex Application project in FlexBuilder
  2. Import KapInspect.swc
  3. Create a new module with the FlexBuilder project wizard, that will extend KapInspectModule
  4. Override registerComponents method in the module, in order to register you plugin(s)
  5. Create a new plugin component, that will implement IKapInspectComponent. You may also directly extend AbstractKapInspectComponent class (that itself extends VBox)
    1. Define a public static string variable "NAME" that will be a unique key for your component (generally name of the class)
    2. Define another static variable "LABEL" to give a readable name to your component
    3. Implements a static function to create the factory for your component, you will specify name, label, class, icon and accept function for your component
    4. override the commitProperties method to update your view (see below), with _target member
    5. if required, implement an accept function for your component: you will accept an object dependind on its type, or any other property

Deploy and run your plugin

  • Compile your flex project (in FlexBuilder, you will need a dummy application in order to compile the project)
  • Your inspection module will be compiled as a SWF that is created under bin directory, inside folders that match the package of the plugin
  • Copy the SWF into your application deployment directory, local or remote
  • Import your plugin into KapInspect, (with "pluginModules" attribute). You will declare your modules in a coma separated list, without any extension
  • Run your application and invoke KapInspect: you should see a new button in the toolbar, with its specific icon (if defined) and the label you chossed as its tooltip

Example

Module class

The following code is the one of MemoryPlugin module. It is very simple, extends KapInspectModule, and its main function is to register the inspectors of the plugin. A single module may register several inspectors, that will become new buttons and context menu entries in KapInspect.

Module class
<?xml version="1.0" encoding="utf-8"?>
<module:KapInspectModule xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" xmlns:module="fr.kapit.module.*">	
  <mx:Script>
    <![CDATA[
	import fr.kapit.introspection.component.ComponentManager;		
	
        override public function registerComponents():void {
	    ComponentManager.instance.registerComponent(MemoryLeakInspector)
	}			
    ]]>
  </mx:Script>		
</module:KapInspectModule>

Inspector class

The following code is an extract of the MemoryLeakInspector class, used in the MemoryLeak plugin of KapInspect.
It shows you how to create the inspector so that it will be recognized by KapInspect.

Inspector class
<?xml version="1.0" encoding="utf-8"?>
<AbstractKapInspectComponent xmlns="fr.kapit.introspection.component.*" 
xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:tree="fr.kapit.tree.*" horizontalScrollPolicy="off" creationComplete="_onCreationComplete()">
	
	<mx:Script>
		<![CDATA[
                        // Defines your plugin icon
			[Embed('resources/icons/components/PluginIcon.png')]
			private static var _icon:Class

                        // IKapitComponent interface. 
                        // Internal name of the inspector, used by the factory
			public static var NAME:String = "MemoryLeakInspector"
                        // Public label of the inspector, visible in button tooltip and inspector tab
			public static var LABEL:String = "Memory Leak Inspector"
                        // This variable tells if your inspector is global (single) or multiple instance. If global, then use the globalPanelName variable to define the tab name and your plugin acts as a Singleton. If not global, there will be a different instance of the plugin for every object inspected with it
			public static var IS_GLOBAL : Boolean = false
                        // Name of the tab for this inspector, in case it is a global inspector
			public var globalPanelName:String = "Memory leaks"
			

			// Factory for the inspector. Must be a static getter function
                        /* The signature of this function is:
public function KapInspectComponentFactory(name:String,label:String,componentClass:Class,						iconOn:Class=null,iconOff:Class=null,iconOver:Class=null,				isAcceptable:Function=null,shortcut:KapInspectShortcut=null)
                         iconOn, iconOff, iconOver are icons for the button in the toolbar
                         isAcceptable is a function whose prototype is :
                         private static function _isTargetAcceptable(target:Object) : Boolean{
                                //TODO: return true or false, generally based on the class of the target, to indicate if this object is accepted or not.
			}
                        This function will be called with the object targetted by the inspector, and will return false if the object is not accepted by it (ex the display list inspector only accepts DisplayObject). If not defined, then true will be always the default and all objects will be accepted.
                        shortcut defines a custom shortcut:
public function KapInspectShortcut(alt : Boolean, ctrl : Boolean, shift : Boolean, keyCode : uint, name : String), see ASDoc for more information
                        */
			public static function get factory():KapInspectComponentFactory {
				return new KapInspectComponentFactory(NAME,LABEL,MemoryLeakInspector,null,null,null,null,													  new KapInspectShortcut(false, true, false, 0x4D /*Ctrl+M*/, NAME))
			}
			

                        // Override this method to update your view depending on _target member
			override protected function commitProperties():void {
				super.commitProperties()
				...
			}


You see that this class extends AbstractKapInspectComponent, which is a convenient method to implement your plugin.
The source of this class is displayed below:

AbstractKapInspectComponent class source
package fr.kapit.introspection.component
{
	import fr.kapit.introspection.ClassUtils;
	
	import mx.containers.VBox;

	public class AbstractKapInspectComponent extends VBox implements IKapInspectComponent
	
	{
		[Bindable] protected var _target:Object 
		protected var 		_targetChanged : Boolean
		public  var 		targetName:String
		public  var 		host:Object
		private var 		_class : Class 
		
		public function AbstractKapInspectComponent()
		{
			super();
			_class = ClassUtils.getObjectClass(this)
		}
		
		public function get componentName() : String {
			return _class["NAME"]
		}
		
		public function get componentLabel() : String {
			return _class["LABEL"]
		}
		
		public function get target() : Object
		{
			return _target
		}

                // This method is called the first time that inspector is opened
		public function setRoot(target:Object, name:String="", host:Object = null) : void
		{
			this.targetName = name
			this.host = host
			this.target = target

		}
		
                // This method is called when the target changes
		public function set target(target:Object) : void
		{
			if ( target != _target ) {
				var factory:KapInspectComponentFactory = ComponentManager.instance.getComponentFactory(componentName)
				if ( factory && factory.canAccept(target)) {
					_target = target
					_targetChanged = true
					invalidateProperties()
					invalidateDisplayList()
				}
			}
		}		
		
		// To override in order to clean view
		public function dispose() : void {
			
		}
	}
}

This class exposes the "_target" protected property, that contains the object to be inspected.
When the user invokes an inspector with a new object, the target setter is invoked, and _target member is updated. Then properties are invalidated.
The clean way to develop your plugin is to override commitProperties in the following way:

commitProperties
override protected method commitProperties() : void {
  super.commitProperties()
  if ( _targetChanged ) {
    _targetChanged = false
    // Do whatever is needed here to update your view using _target property
  }
}

The cinematic of inspector is the following:

  • setRoot() is called at first opening of the inspector
  • set target() is called with the object to be inspected, that has been selected by the user so that the inspector may refresh itself.
    Note that in KapInspect, the target object will be setted only once, ie when the inspector is created, because KapInspect keeps a separate inspector for every object inspected.

The only method to be overriden is actually commitProperties.

Related Projects

Top News

Latest Updates: 2012/01/17

Release on:

Need Information?

Why Kap Lab?

Kap Lab exists because in innovation we trust. Enjoy our products and help us to give you the best.

Cyril Daloz
CEO Kap IT

Adaptavist Theme Builder (3.3.5-conf210) Powered by Atlassian Confluence 2.10.3, the Enterprise Wiki.