Lambda » Flash http://sroucheray.org/blog Stephane Roucheray's trivial work and thoughts Sun, 27 Jun 2010 13:30:08 +0000 en hourly 1 http://wordpress.org/?v=3.0 How to insert a SWF file in an ASDoc API documentation ?http://sroucheray.org/blog/2010/02/how-to-insert-a-swf-file-in-an-asdoc-api-documentation/ http://sroucheray.org/blog/2010/02/how-to-insert-a-swf-file-in-an-asdoc-api-documentation/#comments Tue, 02 Feb 2010 15:22:49 +0000 Stéphane Roucheray http://sroucheray.org/blog/?p=605 ASDoc with inline SWF file

ASDoc API documentation is well designed for developers but remain difficult to read for others. Some of my co-workers are web designer. They code a bit but they want API to be simple and they want usage examples. In the past days I developed some image filters and effects for them. The resulting API has very few meaning without a real example of code and a way to test it. Thus, I wanted them to be able to access the code examples as well as being able to test the result of each effects, inline, in the ASDoc documentation. Click the image below to see the rendering SWF tester.

Effect tester

Code examples are easy to integrate using the @example and @includeExample (Flex 4), but there is no default way of inserting SWF files directly (as far as I know).

In order to insert a SWF file in a generated ASDoc API documentation, one needs to understand the process of generating documentation with ASDoc. On one side there are packages and classes, on the other side ASDoc templates files. Generating documentation consists for the asdoc.exe application of parsing the classes for any special comments and injecting what has been found in the templates. The result is output in a directory and is made of a bunch of HTML, CSS, JavaScript files…

The type of special comments the ASDoc process is looking for looks like that :

/**
 * Apply an RGB distortion effect on a DisplayObject
 *
 * @param target The DisplayObject on which to apply the effect
 */
override public function apply(target : DisplayObject):void{
    ...
}

Special tags starting with an @ can be used in these comments and will be interpreted by the ASDoc process. Fortunately HTML tags can be used as well inside these comments and will be output unchanged. I make use of this feature to insert SWF files inside the documentation.

Step 1 : adding the required JavaScript libraries to the ASDoc templates

Note : in the following section you have to download several components to make it works. I packaged all of them in a zip file.

ASDoc templates are located in a Flex SDK sub-directory by default : FLEX_SDK_DIR\asdoc\templates
To keep unmodified the original templates you can copy this folder outside the Flex directory. In this case to make the ASDoc process being aware of this change use the command parameter -templates-path ‘path/to/your/new/template_folder’
Full ASDoc documentation is located on Adobe Web site

In the template folder locate the file asdoc-util.xsl and in there search for those lines :

<script language="javascript" type="text/javascript">
    <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
        <xsl:text>asdoc.js</xsl:text>
    </xsl:attribute>
</script>

insert the following lines just before the previous ones :

<script language="javascript" type="text/javascript">
   <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
         <xsl:text>jquery.min.js</xsl:text>
    </xsl:attribute>
</script>
<script language="javascript" type="text/javascript">
   <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
         <xsl:text>swfobject.js</xsl:text>
    </xsl:attribute>
</script>
<script language="javascript" type="text/javascript">
   <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
         <xsl:text>swf-loader.js</xsl:text>
    </xsl:attribute>
</script>

As you may guess we will use jQuery and SWFObject to achieve our goal. Download jQuery and SWFObject and put the files in the templates directory (rename the files to match the previous lines). From the SWFObject download ZIP file, extracts the expressInstall.swf file in the templates directory as well.

The third file is made by myself and will help substitute special HTML tags in the documentation by SWF files. Save the following code in the file templates/swf-loader.js

$(document).ready(function(){
    var idBase = "swfLoader";
    var idNum = 0;
    var width, height;
    var params = {
        quality: "high",
        scale: "noscale",
        allowscriptaccess: "always",
        bgcolor: "#FFFFFF"
    };
    var flashvars = {};

    $("div[src]").each(function(){
        $(this).attr("id",idBase + idNum);
        width = $(this).attr('width') || "100%";
        height = $(this).attr('height') || "100%";
       
        var flasvarsString = $(this).attr("flashvars");
        var flashvarsArray = flasvarsString.split("&");
        for ( var i = 0; i < flashvarsArray.length; i++) {
            var flasvar = flashvarsArray[i].split(":");
            flashvars[flasvar[0]] = flasvar[1];
        }
        swfobject.embedSWF(
                $(this).attr("src"),
                idBase + idNum,
                width,
                height,
                "10.0.0",
                "expressInstall.swf",
                flashvars,
                params,
                {}
        );
   
        idNum++;
    });
});

Step 2 : adding special HTML Tag in ASDoc classes comments

Now that the files are in place it’s possible to add special HTML tags in comments to insert SWF files :

/**
 * Creates an RGB distortion effect (Timed effect).
 * <div src='../../../swf/effectTester.swf'
 *   width='780px' height='550px' flashvars='form:mosaicForm'></div>
 */

The div tag will be replaced by the SWF files located at ‘../../../swf/effectTester.swf’ passing width, height and flashvars parameters.
Flashvars must be of the following form :
var1:value1&var2:value2&var3:value3.

Step 3 : where to put the SWF files

Put the SWF files in the doc_output_directory/swf.

]]> http://sroucheray.org/blog/2010/02/how-to-insert-a-swf-file-in-an-asdoc-api-documentation/feed/ 0 Papervision : Mouse interaction with 2D MovieMaterialhttp://sroucheray.org/blog/2009/12/papervision-mouse-interaction-with-2d-moviematerial/ http://sroucheray.org/blog/2009/12/papervision-mouse-interaction-with-2d-moviematerial/#comments Thu, 10 Dec 2009 13:01:55 +0000 Stéphane Roucheray http://sroucheray.org/blog/?p=508 Papervision lets apply textures as MovieClip on 3D object surfaces. This kind of textures is called MovieMaterial. The nature of MovieMaterial gives users the ability to interact with it’s content. However it’s often tricky to make it works.

In the following example I applied a MovieMaterial to a Cube (wihout depth so it looks like a PaperPlane) :

The Flash plugin is required to view this object.

The button and TextField are both children of the MovieClip used as the material in the MovieMaterial. This example shows how the mouse can interact with the button. While it rotates along with the cube and its MovieMaterial, it handles well the three events : mouse over, mouse out and mouse click.

MouseClick on a button inside a MovieMaterial

MouseClick on a button is really easy to implement. A simple listener is added to the button Object :

//WhitePanel class is an asset in the Fla's library
panel = new WhitePanel();

//Set up the okButton inside the panel
var okButton : MovieClip = MovieClip(panel.okButton);
okButton.mouseChildren = false;
okButton.addEventListener(MouseEvent.CLICK, clickListener);

var okInc : Number = 0;

function clickListener (e:MouseEvent):void{
 ++okInc;
 TextField(panel.title).text = "Click on OK Button : "+ okInc;
}

On button click the text field is well updated.

Mouse over and mouse out a sprite inside a MovieMaterial

The mouse over and mouse out events are a little bit more tricky to implement. In general, when a zone is interactive you want the mouse to change its aspects. When over it is transformed to a hand cursor and when out to the simple arrow cursor.
When working on a 2D stage it is done via these affectations :

okButton.buttonMode = true;
okButton.useHandCursor= true; //This is true by default

Thus the hand cursor appears when over the okButton MovieClip. Unfortunately it doesn’t work with Papervision. The workaround is to affect handlers to the MovieClip and globally change the aspect of the mouse cursor :

okButton.addEventListener(MouseEvent.MOUSE_OVER, handleOver);
okButton.addEventListener(MouseEvent.MOUSE_OUT, handleOut);

function handleOver(event:MouseEvent):void {
    //Globally change the mouse cursor aspect
    viewport.containerSprite.buttonMode = true;
    //Not required, changes the aspect of the button
    //in our case
    MovieClip(event.currentTarget).gotoAndStop(2);
}
       
function handleOut(event:MouseEvent):void
{
    //Globally change the mouse cursor aspect
    viewport.containerSprite.buttonMode = false;
    MovieClip(event.currentTarget).gotoAndStop(1);
}

—

Download the demo sources MMInteractionDemo.zip

]]> http://sroucheray.org/blog/2009/12/papervision-mouse-interaction-with-2d-moviematerial/feed/ 0 How to get a mouse hand over a TextField in AS3 ?http://sroucheray.org/blog/2009/11/how-to-get-a-mouse-hand-over-a-textfield-in-as3/ http://sroucheray.org/blog/2009/11/how-to-get-a-mouse-hand-over-a-textfield-in-as3/#comments Fri, 13 Nov 2009 09:16:49 +0000 Stéphane Roucheray http://sroucheray.org/blog/?p=363 It’s pretty simple, buttonMode and mouseChildren properties of the TextField parent should be set like that :

var sprite : Sprite = new Sprite();
var textField : TextField = new TextField();
sprite.addChild(textField);

sprite.buttonMode = true;
sprite.mouseChildren = false;
]]> http://sroucheray.org/blog/2009/11/how-to-get-a-mouse-hand-over-a-textfield-in-as3/feed/ 0 Flash Toolboxhttp://sroucheray.org/blog/2009/09/flash-toolbox/ http://sroucheray.org/blog/2009/09/flash-toolbox/#comments Sun, 27 Sep 2009 10:35:58 +0000 Stéphane Roucheray http://sroucheray.org/blog/?p=272 Last update Wednesday, December 2, 2009

I maintain here some ActionScript3 tools and frameworks I use in my day to day work. This list is not intended to reflect all tools you can Google out there, just the ones I use. If you know something I should test and add here, send me an email.

Editors

Frameworks

JavaScript

]]> http://sroucheray.org/blog/2009/09/flash-toolbox/feed/ 0