HaxeFlixel/flixel — pull request #676 by pixelomatic (2013-10-12 03:23:57+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.