This is the readme for my "Input library" in lua,
currently version 0.1, first release.

If you need help, look for the release thread in the
QJ forums, or drop me a PM, I'm daaa57150 there. But
before, look at this tutorial and at the index.lua
it should be easy.
You can also send me a mail at daaa57150@gmail.com but
I'll answer really slowly there.

If you want to see it in action, you can try my game:
"Mega Asshole Portable" available in the QJ download
section. It's nothing much, and the code is not as
polished as it is in this release but you'll get a
good idea what you can do. I developped this for this
game, only for me but since I find it useful and see
many people asking for this kind of problems in the QJ
forums I just decided to release it. Hope it'll help
you.

Please if you use it, give me credit somewhere.

daaa.



1) WHAT DOES THIS DO:
You'll be able to test those buttons:
cross, square, circle, triangle, L, R, start, select, 
up, down, left, right.
By calling simple functions, you'll be able to know if 
the button is pressed, is just being released, is repeating,
is pressed since long, is just being pressed, during how
long it's pressed, and if the analog stick is touched.

You can set to your needs the repeating interval, the analog
sensibility, and what is considered a long press.


2) WHAT DOESN'T THIS DO:
I haven't included the note, home etc... buttons, 
because I had no use for them when I developped my
game :) and I think the usual functions are enough for those.
But it's easy to add, really.
For the analog stick you can only know if it's touched, 
that's all I needed for my game and since it's analogical,
you'll surely only need the value it gives you.
This also doesn't recognise patterns (double taps, 
half/quarter circles etc), but who knows, I wrote that in
java once and may translate it to Lua someday if I feel 
like it.. But this will be another library.
Also there are a lot of other obvious things this doesn't
do :).


3) HOW TO INCLUDE THIS IN YOUR CODE:
simply add this line at the beginning of your code:

dofile("inputsLib.lua")

and you'll be able to use my functions.


4) FUNCTIONS:
-------------------------------------------------------------
INPUT.update(pad)
-------------------------------------------------------------
Call this at the begining of the main loop or where you
usually call Controls.read(), this is what the "pad" argument
is. If you don't give an argument, the function assumes that
pad=Controls.read(). You can use this facility if you don't
need "pad" anywhere else.

-------------------------------------------------------------
INPUT.firstPress(inp)
-------------------------------------------------------------
Returns true if the button is pressed and wasn't before, 
false otherwise.
The "inp" argument is a string amongst the available buttons,
see 5).
Only the first call to this function will return true, even
if you don't update the inputs between 2 calls. The user
has to release and repress the button for this function to
return true again (and that's what we want, but you can 
easily make a mistake). Store the result in a var if you need
it many successive times.

-------------------------------------------------------------
INPUT.longPress(inp)
-------------------------------------------------------------
Returns true if the button is pressed since a long time,
false otherwise.
The "inp" argument is a string amongst the available buttons,
see 5).
To customize what a "long time" is, see 6).

-------------------------------------------------------------
INPUT.pressedDuring(inp, time)
-------------------------------------------------------------
Return true if the button "inp" is pressed during "time" or
more, false otherwise.
The "inp" argument is a string amongst the available buttons,
see 5).
The "time" argument is the time in milliseconds.

-------------------------------------------------------------
INPUT.isPressed(inp)
-------------------------------------------------------------
Returns true if the button is pressed, even if it was before.
This is the same as Controls.read():<the button>(), but since
you use this library, use this instead.

-------------------------------------------------------------
INPUT.isRepeating(inp)
-------------------------------------------------------------
Returns true if the button is repeating, false otherwise.
This permits to have the same behaviour as a keyboard, when
pressing on a key you expect it to repeat.
The "inp" argument is a string amongst the available buttons,
see 5).
To customize the time between the repetitions, see 6).
Only the first call to this function will return true, even
if you don't update the inputs between 2 calls, and will
return false until the next repetition.
Store the result in a var if you need it many successive 
times.

-------------------------------------------------------------
INPUT.isRepeatingAfterLongPress(inp)
-------------------------------------------------------------
This is the same as above, but before the button repeats, it
has to be pressed since long.
The "inp" argument is a string amongst the available buttons,
see 5).
To customize what a "long time" is, and the delay between
repetitions, see 6).

-------------------------------------------------------------
INPUT.justReleased(inp)
-------------------------------------------------------------
Returns true if the button is not pressed and was pressed
just before.
The "inp" argument is a string amongst the available buttons,
see 5).
Only the first call to this function will return true, even
if you don't update the inputs between 2 calls. The user
has to press and rerelease the button for this function to
return true again (and that's what we want, but you can 
easily make a mistake). Store the result in a var if you need
it many successive times.

-------------------------------------------------------------
INPUT.analogIsTouched()
-------------------------------------------------------------
Returns true if the analog stick is touch in either
direction. The sensibility can be customized, see 6)

-------------------------------------------------------------
INPUT.timePressed(inp)
-------------------------------------------------------------
Returns during how long the button is pressed, in
milliseconds.
The "inp" argument is a string amongst the available buttons,
see 5).


5) BUTTONS NAMES (STRINGS):
"cross"
"square"
"circle"
"triangle"
"l"
"r"
"start"
"select"
"up"
"down"
"left"
"right"

6) CUSTOMIZING:
You can customize those 3 values:

-------------------------------------------------------------
INPUT.setAnalogSensibility(val)
INPUT.getAnalogSensibility()
-------------------------------------------------------------
Functions to get/set the analog stick sensitivity. Default
value is 50, 128 will make it unresponding, 0 will for 
sure detect it as touched even if you don't.


-------------------------------------------------------------
INPUT.setLongPressTime(val)
INPUT.getLongPressTime()
-------------------------------------------------------------
Functions to get/set what "long" means for the "long press"
function(s).
Default value is 350 ms.


-------------------------------------------------------------
INPUT.setRepeatInterval(val)
INPUT.getRepeatInterval()
-------------------------------------------------------------
Functions to get/set the delay between 2 repetitions of a
button, in milliseconds.
Default value is 100 ms.


7)INDEX.LUA:
This file prints on screen which buttons are pressed, if they
are first pressed, just released etc..
You can also see if they are repeating (normal), at the 
exception of left and right, which you see the repetition after
a long press, and they will move the cursor on screen
accordingly. I think this represents what many will want. See
that I stored the value of the repetition in a var for the
functions "INPUT.isRepeatingAfterLongPress" because if I 
called it a second time it would always return false.
You can press start + select a long time to exit the loop,
which will exit the app (Windows), return to Lowser (Lowser) 
or stop the script execution (PSP).

WOW this is also a super button tester :) lol.





