Oh where to start...
Back in the bad old days of strongly typed languages, BASIC interprters ruled the earth and confused bedroom programmers all around the world with their subtle differences between Subroutines and Functions. In laymans terms a Sub (optionally) took some parameters and did some black magic with them and a Function (optionally) took some parameters and did some black magic and then told you what it did via a return value.
This odument iwll only talk about Subs and not Events. The definitions and parameters for the Events are predefined in lapper and
cannot be changed. I have attached a handy reference to this post for you.
A GLscript Sub can do either of these scenarios so we don't have to worrry about whether we declare a particular piece of code as a Sub or Function. So with that history lesson out of the way, how the heck do we use them?
Glad you asked...firstly, let's talk about what types of Subs GLscript has...User Defined and Internal (these aren't the names that Gai uses for them it's just so that I can make a distinction. He probably calls them Peter and Mary, or Pierre and Marie, he being of the French/Italian persuasion).
A User Defined Sub is one that you create and then call directly from within your script, e.g:
<?php
Sub NoParams () # A Subroutine that takes no parameters
privMsg ("We don't need no steeken parameters");
EndSub
...
privMsg ("I'm calling a Sub now");
NoParams;
privMsg ("I'm back! Let's go to the pub!");
...
?>
So in the code above, you create a Sub called NoParams and then you explicity call it from somwhere else in your script and it goes about it's business then returns to where you called it from.
An Internal Sub is one that you create the code for and the Lapper calls it from somewhere else, usually when you click a button:
<?php
# This sub is called by someone clicking on a button
Sub ClickedOn ( $KeyFlags, $id )
privMsg ( "Button clicked was " . $id);
IF ($KeyFlags > 1)
THEN
privmsg ("Left mouse click");
ELSE
privmsg ("Right mouse click");
ENDIF
EndSub
...
openPrivButton (MyButton, 50,50,11,8,1,-1,32,"Click Me", ClickedOn);
...
?>
When you click on the button, Lapper will then run the Sub called ClickedOn and pass it 2 parameters, $KeyFlags and $id. $id is simple enough, it's the name of the button which in this case is MyButton.
$KeyFlags is a little more tricky in that it is an integer (whole number) that will corresond to a value that is defined in InSim as:
<?php
// CFlags byte : click flags
#define ISB_LMB 1 // left click
#define ISB_RMB 2 // right click
#define ISB_CTRL 4 // ctrl + click
#define ISB_SHIFT 8 // shift + click
?>
So if you right click on a button, $KeyFlags will be 2. If you left click while holding the Ctrl key it will be 5. If you left click while holding the Ctrl and Shift keys it will be ummm...8 plus 4, carry the 5, add 3 subtract the age of my dog...13! yeah, thats it. I'm sure it is. Easy huh?
Note: Have a look at my CIF module for handicap configs which has some interesting ways of handling those 2 parameters, as I use an underscore to separate parts of the button name that I can then use to bury other variables in, like the button number or racer UCID.
Coming up...we take a closer look at passing parameters, return values and does being able program actually make you more
attractive to the ladies? (or men if you prefer, who am I to judge?)
So where we? Oh yes, parameters and return values. Take the code below:
<?php
Sub TwoParams ( $param1, $param2) # A Subroutine that takes no parameters
privMsg ("I have 2 parameters " . $param1 . " and " . $param2);
EndSub
...
TwoParams ( "foo", "bar");
...
?>
This defines a Subroutine that takes 2 parameters and just prints them out. It doesn't matter what the parameter names are, you can use whatever you like but I prefer to use names that are significant to the purpose that they are to be used for.
Now this code:
<?php
Sub UserIsAdmin($userName)
IF ( UserIsServerAdmin( $userName ) == 1 || GetPlayerVar($userName,"UCID") == 0 || UserInGroup( "superusers",$userName) == 1 )
THEN
return(ToNum(1));
ELSE
return(ToNum(0));
ENDIF
EndSub
?>
Actually does something useful (I just cut & pasted this from the utils.lpr as it's Friday afternoon and I'm getting tired). It takes someones user name as a parameter and then uses that to see if the user is and administrator and then returns either a 1 or a 0. You can either call it and use it return value to populate a variable like this:
<?php
$IsAdmin = UserIsAdmin("krayy");
?>
or use it directly in the code like this:
<?php
IF ( UserIsAdmin("krayy") == 1 )
THEN
privMsg ("Krayy is a god");
ELSE
privMsg ("No he isn't");
ENDIF
?>
Just remember that a return code can be a number or a string, although i have never tried an array...I'll save that for another thread.
Top tip: Look at other peoples code, particularly things like the utils.lpr as it has some easy to read examples of this sort of thing.
Good luck all!!