The following paragraphs deliver important information about the debugging consoles.
You should take some time to read it in order to fully understand how to use them, and to be aware of the precautions to use.
Architecture
Starting at version 1.0.0 of CairngormConsole and PureMVCConsole, a common architecture is used for both of them.
We have actually designed a framework for these (and possibly other) consoles, and it provides the following features:
- KapITLogger, which is the class that will manage and hold queues of logged information, as well as histories for some of the objects and operations managed (such as Command/Command run or Notification/Notification dispach histories). This logger has the ability to log not only strings (such as the regular Flex logger), but also any AS3 object.
- Default logging and history of all remote services and/or operations (with KapITFXPatches activated, see below), as well as other goodies related to remote services.
- KapITUniversalConsole: seems rather pretentious uh ? This is the root popup window, implementing keyboard shortcuts, used to create any custom console and mainly Cairngorm/PureMVC ones
- Standard History view, that may be used in custom consoles.
OK, this is a bunch of internal information, and you may not care about it.
The important point to remember here is that both consoles work in the same way and offer the same features (which was not the case before). Isn't that great ?
Moreover, thank's to this framework, you'll be able to customize the console to match your own needs, for example:
- Log custom operations and objects of your own, and see them appear as inspectable objects in the main log queue.
- Add custom debug or history views (oops, this one IS available, but not documented yet. You'll have to hack by yourself or to wait for the release of this console framework library)
Keyboard shortcuts
The default startup shortcuts have been enhanced (and debugged also), mainly to help Mac users.
In fact, with MacOSX, a lot of keyboard shortcuts are already used by the system itself, and the default PC shortcut for the console or KapInspect may not work. Actually, it does not work on a brand new Mac OSX, with all of its shortcuts activated.
Hence, we decided to take the host system into account, and to provide different shortcuts for these two systemes.
The shortcuts are made of a prefix for fey modifiers (shift,alt,control), and a keycode or a mouse click.
The default prefixes are now:
- Windows: ctrl+alt
- OSX: cmd+shift new
Hence, shortcuts for the provided consoles will be:
| OS |
KapInspect |
Cairngorm Console |
PureMVC Console |
| Windows |
ctrl+alt+F12 |
ctrl+alt+F5 |
ctrl+alt+F6 |
| MacOSX |
cmd+shift+F12 |
cmd+shift+F5 |
cmd+shift+F6 |
With mouse click instead of keycode (ie ctrl+alt+click), all registered consoles will open at the same time, while the keycode is more selective.
Moreover, it will always be possible to redefine default shortcut, through the "shortcut" properties of all the consoles and KapInspect.
For instance, if you wish to use alt+F11 as a shortcut, declare something like:
<kapit:CairngormConsole shortcut="alt+122"/>
The available modifiers are: ctrl, alt and shift, and on MacOSX, ctrl maps to the command key.
For function keys, codes are: F12 => 123, F11 => 122,..., F1 => 112, etc..
For other keycodes, please refer to microsoft documentation for keyboard codes here
Remote Services debugging
Along with console framework, we provide a special library for remote service logging and debugging. This library actually patches some classes of the Flex framework, in order to add log and history calls to them.
The patched classes are:
- mx.rpc.http.HTTPService
- mx.rpc.remoting.RemoteObject and mx.rpc.remoting.Operation
- mx.rpc.soap.WebService and mx.rpc.soap.Operation
If you want to activate and use the service debugging features of the console, you will just have to include KapITFXPatches.swc library into you project dependencies. The consoles will automatically detect what if a patched version is being used, and will add a Service tab accordingly.
If your project uses several libraries, you just have to include the patch swc at the application project level, not in any library. However, this works only if you use "static linking" of the flex framework, not RSL, which is generally the case.
 | Release builds
You should not use a patched version of the services in your production builds. This will be very easy to accomplish if you use an external build process, with Ant or Maven scripts for example (you should always use external scripts for release builds as releasing directly from FlexBuilder is definitely considered as a bad practice).
Actually, you will have nothing to do to not use the library, as you will not include the patched swc into your relase build scripts. |
Use FlashPlayer Debug to get stacktrace information
The console makes heavy use of the stacktrace to help developers finding the starting line of code for the framework operations.
This works using the following AS3 trick:
var stack:String = new Error().getStackTrace()
And then, parsing the stacktrace to get only the significant part of it.
However, this only works with the debug version of the player, as with the regular flash player, this function is disabled (as it may prevent the application to work in non-debug player).
So in order to take full advantage of this very cool feature, you should always use it with the debug Flash Player.
About garbage collector and memory
The console is somewhat intrusive into your application, in the sense that it creates references to many objects that would otherwise be transient (such as Command or Notification).
As a consequence, these objects will not be released by the GarbageCollector, and will stay in memory, but that should not interfere with the normal behaviour of your application.
However, you must not use any console when you are looking for unreleased references, trying to free memory and to optimize memory consumption of your application, or you could spend hours trying to figure out why all these commands, notifications and other transient objects are still visible in the Profiler windows.
 | Memory Leak Inspector
For finding leaking memory, why not give a try to our MemoryLeak Inspector, a very cool KapInspect plugin for debugging memory leaks ? |
Use KapInspect with the consoles to get even more out of them
You will take even more advantage of the console if you also integrate KapInspect, as you will be able to see even more details on the inspected objects.
If your application embeds both KapInspect and console, then when you will hit Ctrl+Alt+Click, both consoles will display at the same time. However, they also keep their respective shortcuts and may be called selectively.
If KapInspect has been created, ie displayed at least once, you will the be able to send objects from the console into KapInspect, by right-clicking on any item inside any introspection tree, and select one of the available options, such as BindingWatcher, or ClassOutline, for example.
 | Note about the inspection tree
In all screens of the CairngormConsole, you will have an inspection tree available, in order to drill-down and inspect the data that are handled. This tree uses the same component as KapInspect does, so it works exactly in the same way.
You may consult the documentation for it here: http://lab.kapit.fr/display/kapinspect/Developer+guide
If you do not know yet about KapInspect, or do not use it, we recommend you to have a look and to eventually download and integrate it into your application: http://lab.kapit.fr/display/kapinspect/Kap+Inspect |
KapDebug
