Welcome to Kap Lab Store

Integration Guide

Presentation

In order to use KapInspect in your own projects, you will have to either:

  • Create an instance of KapInspect at application startup, which requires to statically link KapInspect.swc, and leads to embedding about 300K into your application. This overload is OK during development stage, but you will certainly wish to avoid such an overhead in production stage. In this mode, you will also be able to create a background event watcher for your application, an to monitor all creation events. You may also choose to use conditional compilation to include KapInspect, in such a way that KapInspect will not be linked into the production version.
  • Create an instance of KapInspectModuleLoader, and dynamically load KapInspect as a Flex Module. In that case, you will have to deploy KapInspect.swf in your application web folder. The size of your application will increase by about 2K only.

Static linking

Import KapInspect.swc

In FlexBuilder, open the Properties box for your project, into "Flex Build Path" / "Library path", add KapInspect.swc

Integration into MXML

Integration of KapInspect into an MXML file is very simple. Just add the following line into your
main application.mxml file:

main application.mxml file
 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" xmlns:kapit="fr.kapit.*">
	...
	<kapit:KapInspect/>	
</mx:Application>

And that's it !

Integration with ActionScript code

The main advantage of creating KapInspect with AS3 code instead of MXML code is to be able to use conditional compilation (not possible with mxml)
You will have to create a new instance of KapInspect as soon as possible (at least if you wish to trace initialization events)
For that, you may use the preInitialize event to do so:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" xmlns:kapit="fr.kapit.*" preinitialize="_onPreInitialize()">

...
  private function _onPreinitialize() : void {
    new KapInspect()
  }
...

Of course, you will prefer to put this code into a

Run you app

Launch your application, and first gives it focus by clicking anywhere in it.
Then hit Ctrl+Alt+F12, and after a second or two (depending of the size of your display list) KapInspect will popup.

Available options

The initialization parameters of KapInspect are :

  • shortcut: this defines the popup shortcut, such as Shift+Ctrl+123 (for Ctrl+Shift+F12, which is the default shorctut)
  • pluginModules: list of inspector plugins to be dynamically loaded at KapInspect creation time (and not at popup time). This must be a comma separated list of plugins module names (without .SWF extension). Defaults to nothing.
  • logApplicationEvents = true|false. If true, then an chained EventLogguer will be created for your application. Try it, and you will know what events are dispatched during initialization phase of your application. All children creation and add events will be monitored at all levels. In this mode, there is no limit to the count of logged events, so this may slow your application especially if the logger is displayed.

Programmatic actions

Once KapInspect integrated into your application, you may use it directly from your code in order to load data to be inspected, or to create event loggers for any object that dispatches standard events (it is not yet possible to trace custom events)
When you use these capabilities, KapInspect will popup with the objects that you specified already inserted into inspectors.

Inspect any object

To add objects into the inspector, do as follow:

add objects into the inspector
 
...
KapInspect.addDebugItem(item,name,host)
...

where :

  • item is the object to be inspected
  • name (optional): name of the attribute that references the item into a host object (host[name] = item)
  • host (optional): reference to the host object, if any, that contains the item through the 'name' attribute

Specifying host and name will help KapInspect to watch changes on the object, if it is Bindable. Name will also be used in the inspector tree as the label of the root node. This will help you to recognize the data.

Create EventLogger programmatically

In some cases, you may wish to trace events dispatched by some EventDispatcher instance in your application:

EventDispatcher
 
...
KapInspect.addEventLogger(item,filters,chainEvents)
...

where:

  • item: the object to be watched for events. It must implements IEventDispatcher. Note that in this version, only "standard" events declared in the Flex frameworks will be watched.
  • filters (optional): an instance of EventFilters class, used to know what event to trace or to filter. By default, the following events will be fitered out:
    • enterFrame
    • render
    • MouseEvent.*
  • This is to avoid too much events to be displayed initially.

  • chainEvents (true|false): If true, then event loggers will be chained on all children that will be created by the initial EventDispatcher item.

Dynamic linking

If you wish to keep your application size low, and even to use KapInspect in production mode (with secret keystroke !), you will prefer to use the Module version of KapInspect

Import KapInspectModuleLoader.swc

Proceed as usual with FlexBuilder in order to add KapInspectModuleLoader.swc library into your project, instead of KapInspect.SWC. As specified below, you application size will grow be a couple of Ko only. Thanks to Flex modules !

Deploy KapInspectModule.swf

You will have to copy KapInspectModule.swf into the folder that also holds your application main SWF. This folder may be either local, either remote on a Web or Application server. If your forget to do so, you will get an error when you try to load the inspector.

Run KapInspect

You will use the same keystroke (Ctrl+Alt+F12 by default) as with the static linking option.

Available options

You may not use the logAApplicationEvents events in this mode (because it requires KapInspect to be loaded with the application), but you may use the 'shortcut' and 'pluginModules' parameters as before.

Available functions

In this mode, you will not be able to add EventLogger programmatically. However it is still possible to add debug items, with KapInspectModuleLoader.addDebugItem method, which has the same signature than its eponym method in KapInspect class.

Related Projects

 Top News

  Latest Updates: 2012/10/05

Released on:

Need Information?

Why Kap Lab?

Kap Lab exists because innovation is our passion. Enjoy our products and help us to give you the best.

Cyril Daloz
CEO Kap IT