how-to guide #002

author: 	tk32
date:	Jan-16-2004


			    
writing more interesting scripts
===================

prerequisites: 
#001 
(you should read how-to #001 before attempting this one)


in this guide we will be grouping our playback functions together into a 
combined playback script.
this is not essential for your own looks, but provides the perfect way to 
introduce you to designing your own scripts.
	
    

Part 1 - a cleaner way to add playback functions
-----------------------------------------------------

for those of you who read how-to #001, we discussed using in-line
functions for the playback buttons, since they only required a single
function. it looked something like this

	"[function onleftbuttonup(this) playStop() end]"

what we will do now is create an interesting script that allows us to add
all of our playback functions from the same script.

we will call our script 'playback'. so your first task is to place the markers for 
the start & end of the script:

	lua playback

	endlua

this script will provide all the functions for all our playback buttons, so we no 
longer have to pollute our beautiful ski with those ugly inline functions.

the first thing we will do is add a variable to the script, called 'type'
when we attach this script to each of our buttons, we will need to tell the script 
how to distinguish between each button, so we will tell the script what type of 
button it is (if we didn't do this, every button would be the same)

	lua playback
		type = nil

	endlua

'nil' means empty, blank, or null.

when we attach the script to our buttons, we will use code like this:

	list scripts string { "playback[type=play]" }
	list scripts string { "playback[type=stop]" }
	list scripts string { "playback[type=next]" }

as you can see, it makes our ski files a lot easier to understand

if you don't believe me, compare these two lines of code:

	list scripts string { "[function onleftbuttonup(this) playStop() end]" }
	or 
	list scripts string { "playback[type=stop]" }


bear in mind, that as far as programming guidelines go, it's not wise to always 
group similar sprites in this way, but since playback buttons are so essential, 
it's nice to have them all wrapped in 1 neat package


part 2 - starting to code the script
--------------------------------------

the first thing we do is make a function that triggers 'on left button up' 
(remember how to do those?)

	lua playback
		type = nil
		function onleftbuttonup(this)
			code...
		end
	endlua

ok, in the code section we need to do different things depending on which 
button it is. so we will use an 'if' statement. 

watch & learn...


	lua playback
		type = nil
		function onleftbuttonup(this)
			if type == stop then
				playStop()
			end
		end
	endlua


how does that look? does it make sense?

'if' code only triggers if the 'statement' is true. in this case, the statement is:

	if the type has been set to 'stop'

remember i said that when we attach this script to our sprite, we will tell 
foo_looks what type of button it is.

	list scripts string { "playback[type=stop]" }

so what we are doing is setting the variable 'type' so that it is 'stop'

when the user clicks on the 'stop' button, it triggers the function, and then, 
because the type is equal to 'stop' it satisfies the 'if' statement and triggers 
the function 'playStop()'


it's worth noting now the difference between '=' and '=='

using '=' sets a variable, and using '==' checks to see if 2 things are the same

'=' means "equals"
'==' mean "is equal"



i hope i havn't lost anybody here. this is our first step into the world of functional 
programming. if you've done and C++ / Pascal programming before, this will make 
a lot of sense.


if not, just be patient - it's really not that hard.



part 3 - adding more 'if' statements
---------------------------------------

ok, so now our script works when you set the type to 'stop', but if you set the 
type to anything else, it doesn't do anything.

so lets add 2 more 'if' statements
(note - we will not put a 'play' clause yet, because we want to do something 
more complicated with our play button)


	lua playback
		type = nil
		function onleftbuttonup(this)
			if type == stop then
				playStop()
			end
			if type == prev then
				fb2k_playSkipStart(-1)
			end
			if type == next then
				fb2k_playSkipStart(1)
			end
		end
	endlua


ok, so far so good.
our script now works if you set the type to 'stop', 'prev' or 'next'.

before we talk about how to implement the play button, i'd just like to 
clear the code up a little.

instead of having seperate if statements, we can combine them all into one.

	if type == stop then
		playStop()
	elseif type == prev then
		fb2k_playSkipStart(-1)
	elseif type == next then
		fb2k_playSkipStart(1)
	end

do you prefer it like this?? it works exactly the same, but is a little neater


part 4 - adding a custom function
-------------------------------------

like many users, i like my play button to act as a play/pause button.

this requires slightly more code than the other buttons, since we must check if 
fb2k is currently playing/paused/stopped.

we will do this in our first ever 'custom function'.
(it is not necessary to make a custom function for this, but it's a nice opportunity
to show you how)

custom functions do not trigger automatically (like the ones with handlers).

the only time a custom function triggers, is when it is called by the script

let me show you first, then you'll undertsand better:

	lua playback
		type = nil

		function playPause(this)
			code...
		end

		function onleftbuttonup(this)
			if type == stop then
				playStop()
			elseif type == prev then
				fb2k_playSkipStart(-1)
			elseif type == next then
				fb2k_playSkipStart(1)
			elseif type == play then
				playPause()
			end
		end
	endlua


ok, several things to point out here:

- i have writen a custom function called 'playPause'
- i have added a 3rd 'elseif' statement to check for 'type == play'
- when 'type == play', the script triggers my custom function

ok, now onto the playPause function



part 5 - coding the playPause function
------------------------------------------

before coding a function, you should think, in plain english, how you want it
to work

here's how i want my play/pause button to work:

	if fb2k is playing, then pause the track. otherwise, start playing the track.


and here is how i translate this into LUA code


	if fb2k_isPlaying() then 
		fb2k_playPause() 
	else 
		fb2k_playStart() 
	end

and since it is short, i can even condense it onto a single line

	if fb2k_isPlaying() then fb2k_playPause() else fb2k_playStart() end


notice i am using 'else' instead of 'elseif'. this is because i don't care about anything
else. 
in other words, if fb2k is doing anything else, then start playback


part 6 - the finished script
-----------------------------

we have now completed the script. it should look like this:

	lua playback
		type = nil
		function playPause(this)
			if fb2k_isPlaying() then fb2k_playPause() else fb2k_playStart() end
		end
		function onleftbuttonup(this)
			if type == 'prev' then fb2k_playSkipStart(-1)
			elseif type == 'playpause' then playPause(this)
			elseif type == 'stop' then fb2k_playStop()
			elseif type == 'next' then fb2k_playSkipStart(1)
			end
		end
	endlua


and we can attach this script using any of the following methods

	list scripts string { "playback[type=stop]" }
	list scripts string { "playback[type=play]" }
	list scripts string { "playback[type=prev]" }
	list scripts string { "playback[type=next]" }


part 7 - taking things further
--------------------------------

if you are excited to develop this script further, you can try 2 things -

1. 

you could try adding more 'type' statements, so you could have support for
a 'pause' button, or a 'random' button, etc...

2. 

you might like to code a 2nd handler function for 'onrightbuttonup'

this way you could add functions for when the user clicks the right mouse button.

use this example to get you started:


	function onrightbuttonup(this)
		if type == 'prev' then fb2k_playStart()
		elseif type == 'next' then fb2k_menuCommand('Playback/Random')
		end
	end


these two examples make the 'prev' button restart the current track, and the 'next'
button play a random track, when they are clicked with the right mouse button.


IMPORTANT NOTE:
==========

all functions, and all 'if' statements, must always have a declared 'end'.
if there is not an end for each of these, then your script will not work

the reason for this is because foo_looks thinks that the script has not finished, and
continues to read down the page assuming everything else is part of the same script.

if you are using the 'elseif' feature, you only need 1 'end', after the last statement.


so if you do get errors, it's most likely because you don't have enough 'end' words.

----


a list of all available functions is available here:

http://www.btinternet.com/~sean.m.kelly/functions_list.txt

(the descriptions of each function are coming soon)




be creative & have fun...




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

this concludes how-to guide #002

you should regularly check the 'foo_looks 2.0 resource pages' for further 
mini-guides ike 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