mikemo

Is there a feature missing from the Flex Builder debugger that you really wish we had put in?

No? Right, move along then.

Oh, what’s that? Yes, there is such a feature? Well then, now is your chance for fame and glory. (Notice I didn’t say fortune. That part probably takes more work than just writing a plugin.)

There is bad news and good news. The bad news is, in this release we will not be publishing the Flex-specific debugger APIs that live inside Flex Builder. We just haven’t had time to clean them up and test them to the degree that we would be comfortable releasing them as documented, supported APIs.

But, the good news is, our lack of Flex-specific APIs is not as big a problem as it might sound like at first, because Eclipse itself has a very clean, well-documented set of APIs for accessing generic debugger-related functionality (variables, breakpoints, callstacks, etc.). And it turns out that the vast majority of stuff that you can think of putting into a Flex Builder debugger plugin is actually generic debugger stuff, not Flex-specific.

For example, using the Eclipse APIs, here are a few things you can easily do within your own Flex Builder plugin:

• given a string, evaluate it as an expression
• change the value of a variable
• set a breakpoint
• determine the current callstack
• programmatically invoke step-into, step-over, resume, terminate, etc.

Okay, so where to start? In future posts I will give some actual code samples, but for now, here are a few key starting points inside Eclipse:

• Much of the key stuff is in the Java package org.eclipse.debug.core.model — this includes IVariable, IValue, IThread, IStackFrame, IDebugTarget (a program being debugged), IProcess (a program that was launched with either Debug or Run), IBreakpoint, ILineBreakpoint, IExpression, IWatchExpression.
• Also, a common starting point for getting anything done is a call to org.eclipse.debug.core.DebugPlugin.getDefault(). From there, you can get to the IBreakpointManager, ILaunchManager (again, a “launch” is anything that you launched with either Debug or Run), and IExpressionManager; and add a debug event listener so your code is notified when something interesting happens.
• Finally, class org.eclipse.debug.ui.DebugUITools has some useful helper functions. In particular, DebugUITools.getDebugContext() is more important than its bland name implies. The “debug context” is whatever is selected in the Debug view, such as a particular stack frame. This ends up affecting lots of things, like which variables are shown in the Variables view, and how expressions are evaluated: Expressions are evaluated in the context of the current stack frame.

The online documentation for all the Eclipse debugger classes is here (scroll down to the org.eclipse.debug.* packages).

Finally, I want to warn you that learning how to write Eclipse plugins is a very time-consuming undertaking. Eclipse is extremely modular — there are design patterns everywhere you turn. And that’s a good thing, because it gives you tremendous power to plug into it at any level (if this weren’t the case, we wouldn’t have been able to create something like Flex Builder on top of it).

But the downside of this modularity is that it’s really hard to just plunge in and start creating useful code, because it can be very hard to figure out how to get from point A to point B. (An example: Early on, I tried to figure out the code path from “user double-clicks in the margin of a document” to “blue circle shows up indicating a breakpoint has been created.” Whoo boy.) It took me about a month of full-time development before the lightbulb in my head finally lit up and I “got” how everything fits together; I then began to find it much quicker to write code.

This is probably documented somewhere — it is a standard feature of Eclipse — but I thought I would mention that if you want to view and/or edit the properties of a launch configuration (you know the Run > Debug… or Run > Run… dialog), a shortcut to do that is to click the Debug or Run dropdown icon on the toolbar, and then control-click on the configuration you want to edit. A regular click, of course, will launch that configuration; but a control-click will bring up the dialog to edit it.

Naturally, Flex Builder does syntax coloring when displaying your .mxml, .as, and .css files. As of this first release, we don’t have a way for you to change the colors that are used. But if you don’t like them, you can change them — just please be aware that this technique is entirely undocumented and unsupported. (Doesn’t that just give you a thrill? Funny how learning about anything which is undocumented — even something as trivial as this — makes you feel like you’re stickin’ it to the man.)

Anyway, inside your Flex Builder directory, look for a folder called

    plugins\com.adobe.flexbuilder.editors.common_2.0.xxx

where xxx is a version number — for example, 340 for Beta 3.

Inside that directory is a file called common.jar. Open this file with WinZip or any other zip software. (In case you didn’t know, Java .jar files are actually the sample file format as .zip files. Probably the easiest way to open the file is to copy common.jar to common.zip, and then just double-click it.)

In there, you will see Colors.xml. That’s your baby. Oh, the excitement, we’ve found the top secret undocumented stuff! The format of the file is pretty obvious: an XML file with three sections — one for ActionScript, one for MXML, and one for CSS. Just modify the following attributes of any tag:

• text="rrggbb" — foreground color (standard red/green/blue format)
• bold="true" or "false"
• italic="true" or "false"

Then when you’re done, save your modified Colors.xml back into common.jar (after first making a backup of common.jar, of course.)

In case it wasn’t obvious: This whole thing is undocumented and unsupported. You do this AT YOUR OWN RISK. And, of course, it may change in future versions of Flex Builder. In fact, it probably will change, when we eventually add support for customizing your colors.