CAAT.Foundation.Actor

Clip

Clipping is by default disabled on CAAT. Enabling it results in slower performance, so it must be treated carefully. It can be enabled globally by setting CAAT.Foundation.Actor.prototype.clip= true.

Optionally, you can enable/disable clipping for individual actors by calling the method setClip(bool, path).

Parameters for this method are:

a boolean indicating whether clip is enabled.
path. This parameter is optional. If not supplied, a rectangle equal to the actor size will be used as clipping area. If set, this parameter must be a CAAT.Path instance. This CAAT.PathUtil.Path can also have CAAT.Foundation.Behavior objects applied. It will only honor CAAT.Behavior.ScaleBehavior, CAAT.Behavior.RotateBehavior and CAAT.Behavior.PathBehavior object instances, so that the mask can be rotating, scaling and translating all together.

The following sample code could be used to define a CAAT.PathUtil.Path instance as clip area as well as adding some behaviors to the clipping mask.


            // define a path
            var path =
                        new CAAT.Path().
                                beginPath(100, director.height / 2).
                                addCubicTo(
                                100, 10,
                                director.width - 100, 10,
                                director.width - 100, director.height / 2).
                                addCubicTo(
                                director.width - 100, director.height - 10,
                                100, director.height - 10,
                                100, director.height / 2).
                                closePath();

            // define another path instance to make the traverse traverse across.
            var traversePath= new CAAT.Path()...;

            // add to the mask a behavior to traverse the path,
            path.addBehavior(
                new CAAT.PathBehavior().
                    setValues( traversePath ).
                    setFrameTime( 0,15000 ).
                    setCycle( true ).
                    setTranslation( path2.width/2, path2.height/2 )
            // and a rotation, so that it rotates while traversing.
            ).addBehavior(
                new CAAT.RotateBehavior().
                    setValues( 0,Math.PI*2 ).
                    setFrameTime( 0,5000 ).
                    setCycle( true )
            // add as much as needed.
            ).addBehavior(
                ...
            );

            // enable clip on a CAAT.Actor instance (container, button, whichever) with
            // the given path shape as clip area.
            actor.setClip( true, path );

This method is a powerful feature which allow to set arbitrary paths as clippling areas. See this example for a visual demo.

Clip will work only on canvas and DOM/CSS renderers. GL won't have any clip applied. Arbitrary clip areas can only be used on Canvas renderer.

Example

This example allows dragging of shown actors. Use shift+alt+control to modify default drag behavior. One of the Scene Actors will have clipping enabled. You'll see that in one instance you're able to drag the inner green Actor outside the Magenta one area. But after dropping it outside its parent area, you won't be able to gain mouse control over the inner Actor again. This is because of the way CAAT routes events to its Actors. In order to send an event to an Actor, the Actor must be contained into its parent area. Period.

It also defines an elliptical clip area on the scene.


                var _director_5= new CAAT.Director().initialize(
                        600,
                        200,
                        document.getElementById('_c5') );

                var _scene_5= _director_5.createScene().setFillStyle('#c0c0c0');

                for(var i=0; i<2; i++ ) {

                    // rectangle shaped actors of 80x80 pixels.
                    var s = 80;

                    // containers can contain other actors or containers.
                    var _c5_container = new CAAT.ActorContainer().
                            setBounds(i*400+10, 20, s, s).
                            setRotation( Math.PI*2*Math.random() ).
                            setFillStyle('#ff3fff').
                            enableDrag().
                            setClip( i==0 );

                    // set container paint routine to draw an arrow
                    _c5_container.paint= function(director, time) {

                        var crx= director.ctx;

                        // fill actor
                        crx.fillStyle= this.fillStyle;
                        crx.fillRect(0,0,this.width,this.height );

                        // outline it.
                        crx.strokeStyle= 'black';
                        crx.strokeRect(0,0,this.width,this.height );

                        // draw a white arrow. just to point where position 0,0 is.
                        crx.strokeStyle='white';
                        crx.beginPath();
                        crx.moveTo(5,10);
                        crx.lineTo(20,10);
                        crx.lineTo(15,5);

                        crx.moveTo(20,10);
                        crx.lineTo(15,15);

                        crx.lineWidth=2;
                        crx.lineJoin='round';
                        crx.lineCap='round';

                        crx.stroke();
                    };

                    // add actor to scene.
                    _scene_5.addChild(_c5_container);

                    // create a container.
                    var _c5_container_child= new CAAT.ActorContainer().
                            setBounds(s/2,s/2,s/4,s/4).
                            setRotation( Math.PI*2*Math.random() ).
                            setFillStyle('#00ff00').
                            enableDrag();

                    // set a custom paint function for children inside containers.
                    _c5_container_child.paint= function(director,time) {
                        // call default container paint method.
                        CAAT.ActorContainer.superclass.paint.call(this,director,time);
                        var ctx= director.ctx;

                        // fill a white circle of 10x10 pixels at position 2,2
                        // just to show where 0,0 is positioned on screen.
                        ctx.fillStyle='white';
                        ctx.beginPath();
                        ctx.arc(7,7,5,0,2*Math.PI,false);
                        ctx.fill();
                    }

                    // add this container as a child of the previous created container.
                    _c5_container.addChild(_c5_container_child);

                    );

                    // set an elliptical clip area
                    _scene_5.setClip(
                        true,
                        new CAAT.Path().
                            beginPath(10,_director_5.height/2).
                            addCubicTo(
                                10,10,
                                _director_5.width-10,10,
                                _director_5.width-10,_director_5.height/2 ).
                            addCubicTo(
                                _director_5.width-10,_director_5.height-10,
                                10, _director_5.height-10,
                                10, _director_5.height/2 ).
                            closePath()
                    );

                }

                CAAT.loop(20);