Flex Conditional Compilation with Clipboard

A particularly handy use of Flex's conditional compilation is to control when debugging information is output or otherwise handled. I discussed placement of fault information on the clipboard in a previous blog entry. In that blog entry, I included a call to place fault information on the clipboard (flash.system.System.setClipboard(<<yourFaultString>>)) in the standard ActionScript fault handler method I had written. The only downside to doing it this way is that fault information would also be placed on all users' clipboards during production use of this code. The virtue of conditional compiling in this case is clear -- we can use conditional compiling to only include the flash.system.System.setClipboard call when in development mode or debugging mode.

Here is an example of using Flex's conditional compilation to only place fault information on the clipboard when in debugging mode. This example is a simple example of a fault handler method that might be used and which will only place the fault information on the clipboard when in debugging mode.

/**
 * Generic failure/fault handler.
 *
 * @param aEvent Failure/Fault event to be handled.
 */
function handleFault(aEvent:FaultEvent):void
{
   const mName:String = "handleFault(aEvent)";
   const fault:Fault = aEvent.fault;
   const messageString:String =
        "faultCode: " + fault.faultCode + "\n\n"
      + "faultString: " + fault.faultString + "\n\n"
      + "message: " + fault.message + "\n\n"
      + "rootCause: " + fault.rootCause;
   trace( mName + ": " + messageString );
   Alert.show(messageString);
   CONFIG::debugging
   {
      flash.system.System.setClipboard(messageString);
   }
}

The lines 17-20 above emphasize the conditional compiling and the call to setClipboard that will only occur when CONFIG::debugging is true.

With that code created, the next step is to set the value of CONFIG::debugging. This is set by using the -define compiler flag for the mxmlc compiler.

The next code snippet shows how this might be accomplished in Ant (Flex Ant tasks could also be used and are available from Adobe Labs for Flex 2 and are built-in to Flex 3).

<exec executable="mxmlc">
   <arg value="${dir.app.flex}/FlexSlidesExamples.mxml" />
   <arg line="-debug=${flex.debug}" />
   <arg line="-define=CONFIG::debugging,${flex.debug}" />
   <arg line="-use-network=${flex.network}" />
   <arg line="-output ${dir.app.build}/${file.swf}" />
</exec>

For convenience, I set the flex.debug property in the build.properties file as either flex.debug=true or flex.debug=true. Note that this value is the same value I use to control whether the .swf compiled file will support debugging.

In a real application, of course, you'd probably want to use conditional compiling as shown here to limit even what is shown on the Alert.show pop-up because it is not likely you want to expose all of those details to users who mostly don't want to see them either.

UPDATE (22 April 2008): As asked in the comment section below and as I responded, conditional compilation appears to be a feature unique to Flex 3 (or, at least, Flex 2 doesn't support the Flex 3 mxmlc compiler option as shown in this blog entry). The two screen snapshots below show conditional compilation with Flex 3's and Flex 2's mxmlc command. As the screen shots show, it compiles successfully for Flex 3, but does not recognize the -define option for Flex 2.

Successful Conditional Compilation with Flex 3


Unsuccessful Conditional Compilation with Flex 2


I have one other update to this blog entry (also updated on 22 April 2008). When one adds the CONFIG::debugging label to the Flex code, it must thereafter be provided to the mxmlc compiler. The next screen snapshot demonstrates the error message seen if this is not passed into the mxmlc command with the -define option.