how-to guide #001

author: 	tk32
date:	Jan-14-2004


			    
adding functions to your button sprites 
========================


this guide will pick up where the tutorial left off.

if you remember, we had code that placed 2 buttons in our look (play & stop)

we also set a statemap for the buttons, so that they have rollover & press effects.

so now all that is left to do is add their functions.


first, let's discuss what this means:

when i talk about adding functions to sprites, what i really mean is 'attaching a script 
to the sprite'. we use scripts (written in LUA) to control our look's interaction with the 
Foobar2000 software.

the great thing about scripts, is that they can be as simple, or complicated, as you 
require.

Luckily, our first use of scripts will be a very basic one, and adding playback controls is 
a great way of introducing it.


part1 - how to attach a script
---------------------------------

if you have written a script for your look, you can attach it to a sprite by name.
you may remember when reading through the tutorial that we did exactly this with the 
common script named 'dragLook'

(common scripts are those that were imported from the file 'foo_looks_common.ski')

we attached this script (dragLook) to the background of our look so that we could drag 
the look around the desktop.

the code we used was as follows:

	list scripts string { "dragLook" }


the reason we attach scripts in a list in this way, is so that we can attach any number 
of scripts...

	list scripts string { "dragLook", "hideOnRollover", "flashOnPause" }   etc....


the 2 extra scripts given here are just examples, and are not common scripts (although 
you might like to try coding them when you get more experienced)


part2 - examing a basic script (dragLook)
---------------------------------------------

we will now quickly examine the basic script used in the previous paragraph, named 
'dragLook' 

the code looks like this:

	lua draglook
		function onleftbuttondown(this)
			look_drag()
		end
	endlua

if you've ever done any type of computer programming, you should recognize the layout 
of the script. don't worry if you havn't - i will explain the syntax now.

just like when coding in html, all scripts must have a clear start & end tag.

	lua scriptname
		type code here....
	endlua

this tells foo_looks where your scripts start & end, and also tells it the name of your 
new script.

inside these boundaries, you type 1 or more functions.

functions must have beginning and ends also.

	function name
		code goes here...
	end

the name you give your functions determine when they are triggered. for example, the 
function in the script 'dragLook' is triggered whenever the left mouse button is pressed 
down 

	function onleftbuttondown(this)

this is called a 'handler'. there is a list of all supported handlers at the following address:

	http://www.btinternet.com/~sean.m.kelly/foo_looks/script_ref.htm

we use the word 'this' in brackets to tell foo_looks which part of the look the user has 
clicked on. don't worry, it will make more sense later.

finally, we come to the actually code:

	look_drag()

this is a built-in command that drags the look around. when you write a script, the only 
way to control the foobar2000 application is by using built-in functions

all built-in functions either start with 'look_' (if they do something to the look) or 'fb2k_' 
(if they do something to fb2k)

some examples:

look_drag()		- as we've discussed
look_hide()		- closes the look, but keeps fb2k running
look_updateTagz()		- updates the TagZ display

fb2k_playStop()		- stops playback
fb2k_setVolume(value)	- sets the volume to 'value'
fb2k_playbackSeek(seekpos)	- jumps to 'seekpos'


for a complete list of available functions:

http://www.btinternet.com/~sean.m.kelly/functions_list.txt
(descripts of functions coming soon)


part3 - using this knowledge to write our first script
--------------------------------------------------------

ok, now we're going to write our first script. it's called 'playbutton'
(yes, it's fine to name the scripts the same as the sprites)

it looks like this:

	lua playbutton
		function onleftbuttonup(this)
			fb2k_playStart()	
		end
	endlua

ok, paste this code into your ski file (but make sure it is seperate from a sprite or 
section declaration)

now we need to attach it to our play button. do you remember how??

yes, you need to add this line to the button of your 'playbutton' sprite:

	sprite playbutton
	.....
	list scripts string { "playbutton" }

now save your ski, and try using the play button.... it works!!


.. ok, now use this knowledge to write another script for you stop button

the built-in function you need to use was mentioned earlier. it is:

	fb2k_playStop()


we'll continue once you've got both buttons working.



part4 - this is all working nicely.... but do i have to write a script for every sprite??
------------------------------------------------------------------------------------------

the answer is no.. you can use 'inline functions' whenever you only need to perform 
a basic action like those above

so here's the same functionalty, but using an inline function definition:

	sprite playbutton
	.....
	list scripts string { "[function onleftbuttonup(this) fb2k_playStart() end]" }

	sprite stopbutton
	.....
	list scripts string { "[function onleftbuttonup(this) fb2k_playStop() end]" }


notice how much mosre suitable this method is.

you can even have more than 1 inline function. look at this example:

	sprite closebutton
	....
	list scripts string { "[function onleftbuttonup(this) look_hide() end]", 
	"[function onrightbuttonup(this) fb2k_menuCommand('Foobar2000/Exit') end]"  }


so the 'closebutton' will 'hide' on the left button, and 'exit' on the right button.

notice that this declaration spills over onto the next line, but that's fine as long as it is bracketed correctly.

all inline functions must be placed inside square brackets, and must use a valid handler

	"[function handler(this) operation end]"


inline functions are perfect for sprites like the playback buttons. but for anything more serious, you'd be best to use a full script



part5 - adding the remaining buttons
----------------------------------------

your task now, is to design some buttons for the previous, next & pause buttons.
then to code them, and finally add inline scripts for them

to get you started i will tell you the built-in functions that are suitable for the remaining 3 buttons:

for pause: 	fb2k_playStop()
for previous:	fb2k_playSkipStart(-1)
for next:		fb2k_playSkipStart(1)



===============

this concludes the how-to guide

you should regularly check the 'foo_looks 2.0 resource pages' for further mini-guides like this

http://www.btinternet.com/~sean.m.kelly/foo_looks/



if you have any questions/problems/suggestions, you can email me at:

tkelly32@btinternet.com