Parameters [WAS: Main menu puzzle]

[J. Landman Gay]

Mark Swindell wrote:
> 
> Parameters are, to me, the least well-explained and  least 
> intuitive aspect of Rev (and programming in general).

The concept of parameters can be very tricky for lots of people new to 
programming. I've explained it before on other lists, but I can't find 
my old notes. But let me take another shot at it here.

A parameter is simply a variable that is declared at the start of a 
handler. My favorite analogy for a parameter is a "basket". Your script 
states that there is a basket (a variable) available to hold some 
information. The Rev engine then fills that basket with something when 
it sends the corresponding event message. Your script can then use the 
information inside that basket however it wants.

Let's look at the menupick message, since that's the one that came up on 
the list:

on menupick myBasket
   ...

By putting "myBasket" after the handler declaration, we have defined 
that there is a parameter variable available to hold whatever data  the 
engine sends. In the case of menupick, the data that fills that basket 
will be the name of the menu item the user has chosen. The variable 
"myBasket" will therefore hold something like "Exit" or "Copy".

Like any other variable, it doesn't matter what you name the basket. The 
parameter can be named anything; it is merely the act of naming it and 
including it in the handler declaration that is important. In general, 
it is best to name parameters in a way that describes what they will 
contain. This helps a great deal later on when you are reading a script 
and you need to remember the kind of data that the variable contains.

Therefore, in the case of a menupick parameter, a good name for the 
parameter variable might be "userChoice", or "userItem" or something 
similar. Some people like to name parameter variables prefaced with a 
"p" (i.e., "pUserChoice") so that they remember when reading the script 
later on that it was a variable passed as a parameter rather than a 
variable they declared in the script. This isn't a rule, just a 
convention that some people like to follow for clarity.

You can have any number of parameters declared in a handler:

on myHandler pOne,pTwo,pThree <etc>
  ...

If the engine (or one of your own handlers) passes three parameters to 
this handler, each parameter "basket" will hold one of the items that is 
passed to it.

If more parameter items are passed than you have declared parameter 
"baskets" to hold, the extra ones are not available to your script. 
(There is a way around this using "the params" but that is more advanced 
than we want to talk about here.)

If fewer parameter items are passed to your handler than you have 
"baskets" declared, the extra baskets are empty.

Feel free to ask for clarification, I wrote this very quickly.

-- 
Jacqueline Landman Gay         |     jacque at hyperactivesw.com
HyperActive Software           |     http://www.hyperactivesw.com