HaxeFlixel/flixel — pull request #675 by pixelomatic (2013-10-12 02:55:41+00:00)
Title: Added FlxFlicker class that encapsulates flickering behavior.

Referencing the issue https://github.com/HaxeFlixel/flixel/issues/672, and https://github.com/HaxeFlixel/flixel/issues/672#issuecomment-26152206, https://github.com/HaxeFlixel/flixel/issues/672#issuecomment-26156089 I created the FlxFlicker class. It's usage is very similar to the ```FlxSpriteUtil.flicker()``` method. I kinda overhauled that method with FlickerData object and created this class with some additions.

The most easiest usage is like ```FlxFlicker.basicFlicker(this, 1, 0.02, true, onFlickerFinished);``` which means, flicker every 0.02 seconds for a 1 second duration, keep the object visible after all flickering is done and call onFlickerFinished method when it's complete. This usage recycles a FlxFlicker instance from pool and auto-releases it when flickering is done.

Advanced usage can be done with manually recycling an instance, using it for once or keeping a reference to it and using it again and again. But this way, you should release it into pool if you want to reuse it after you are done. I don't recommend that usage but it's possible though.

The most important point to consider is you shouldn't use a FlxFlicker object after it is released into the pool. As it will end in undefined behavior, caused by having more than one object having a reference to same FlxFlicker object. I'm not sure how I can simplify it better but it can be avoided pretty easily by nulling the reference to the FlxFlicker instance after it is released and you are done with it. It is also true for ```FlxFlicker.basicFlicker()``` if you decide to keep a reference to it, but it is not mandatory. It will be auto-released to pool. This is why I recommend using ```FlxFlicker.basicFlicker()```, just don't keep a reference to it and you'll be okay. You will be called back when it is finished and includes that particular FlxFlicker instance as a parameter of callback if you somehow want to check some property.

Also I've written a pretty detailed documentation and tried to stick close to flixel conventions as much as possible. I can provide a sample by forking and modifying a demo like Mode if you want. I think you will understand as it's API is very similar to the ```FlxSpriteUtil.flicker()``` method.

Beware that I have not thoroughly tested this. But I guess it's favorable to merge this into dev branch and it does not break any existing APIs.