Thursday, November 1, 2012

EasyKeyboard AS3 class: Download and How to Use

EasyKeyboard is a free AS3 library for easy, quick and efficient keyboard management.

The library can be downloaded here (6 kB).

To implement it, simply add the "com" folder to the directory of your folder.

To use, create an instance of the EasyKeyboard class:

var keyboard:EasyKeyboard = new EasyKeyboard(stage);

And now you can use all of its features, as listed and explained below.

It is also very useful if your IDE has a nice feature which displays available methods and properties of the class you're working with. FlashDevelop has this feature, for instance.

Key names for all the "Easy" methods can be found in the keyLabels array in EasyKeyboard.as, they are most of the time pretty straightforward. For example, 65 can be replaced with simply "A" in Easy functions.

Listening to a single key:

Use addListener() or addEasyListener(). Examples:

keyboard.addListener(65, function() { trace("Key A is down!") }, function() { trace("Key A is up!") }, false, false, false, "myListener");

keyboard.addEasyListener("A", function() { trace("Key A is down!") }, function() { trace("Key A is up!") }, false, false, false, "myListener");

Both above lines mean the same thing.

The parameters of the functions are keyCode/keyName, KEY_DOWN handler, KEY_UP handler, alt, ctrl, shift and listener id. The handlers are functions that receive no parameters. The alt, ctrl and shift values are booleans, which, if set to true, make the listener trigger the event if the key is pressed in combination with alt, ctrl or shift respectively. The listener id is a string value that can be anything and is used to later be able to remove this particular listener.

Listening to holding keys:

There are 2 functions for this as well - addHoldListener() and addEasyHoldListener().

keyboard.addHoldListener(65, function() { trace("Key A is down!") }, "myListener");

keyboard.addEasyHoldListener("A", function() { trace("Key A is down!") }, "myListener");

When the key is held down, the handler function is executed each frame.

There are only 3 parameters - keyCode/keyName, handler function and key id.

Listening to key combinations:

The functions here are addComboListener() and addEasyComboListener():

keyboard.addComboListener([65, 83], function() { trace("Combination A+S is down!") }, "myListener");

keyboard.addEasyComboListener(["A", "S"], function() { trace("Combination A+S is down!") }, "myListener");

The event is triggered when both keys are pressed at the same time.

The 3 parameters are: array of keyCodes/keyNames, handler, id.

Listening to key sequences:

With this you can listen to key sequences. For example, you can listen to "CAT" sequence and dispatch an event when the 3 letters are pressed in that order. There are no time intervals between key presses. If the order is not exact, for example, if the user presses "CAST" - the sequence is broken and the event is not dispatched.

Two functions for this - addSequenceListener() and addEasySequenceListener():

keyboard.addSequenceListener([67, 65, 84], function() { trace("Sequence 'CAT' has been pressed!") }, "myListener");

keyboard.addEasySequenceListener(["C", "A", "T"], function() { trace("Sequence 'CAT' has been pressed!") }, "myListener");

The parameters are: array of keyCodes/keyNames, handler function, listener id.

Listening to timed key holds:

The event here is dispatched when the user holds a specific key for a specific amount of time.

The functions are addTimedListener() and addEasyTimedListener():

keyboard.addTimedListener(65, 1000, function() { trace("Key A was pressed (and held for a second)!") }, true, "myListener");

keyboard.addEasyTimedListener("A", 1000, function() { trace("Key A was pressed (and held for a second)!") }, true, "myListener");

The parameters are keyCode/keyName, delay in milliseconds, handler, repeat value, listener id.

The repeat value is a boolean, which, if set to true, will keep dispatching the event forever as long as the key is pressed. If flag is set to false, then it dispatched the event once after the timer stops. To reset the timer, the user has to release the key and press it again.


I hope you find the class useful!

Thanks for reading!

1 comment:

Aimo said...

As always, all very easy to understand and easy to use. I've learned a lot on your blog, and this class I will also actively use.
Thank you, dude!

Post a Comment