• home / lingo

Using me and other parameters in Lingo

Understanding me

The term me is a parameter. A parameter is a variable that is used to add flexibility to handlers or behaviors. When you apply a behavior from the Behavior Palette, often you will be prompted to assign certain parameters to that behavior. The parameters can be thought of as the behavior's properties. It is a Lingo convention to call the first parameter of a handler me.

The term me appears by default after event handlers when you create a frame or sprite behavior. You may have seen but never used it. It can appear as
on exitFrame me
or
on mouseUp me.
The word me has no special meaning. It could be replaced by any word you can think of and will have the same effect. The word me is only necessary if you want to use it as a parameter in the handler.

We could use the following behavior to create a beep sound when a sprite is clicked:
on mouseUp me
  beep
end
The beep behavior above has is no real need for the word me.

Let's look at another behavior with me.
-- sprite behavior to follow cursor horizontally
on exitFrame me
  sprite(me.spriteNum).locH = the mouseH
end

By using me.spriteNum, we are can identify the sprite/channel number (the spriteNum property) of the sprite to which the behavior is attached. The word me becomes a valuable part of the script.
me.spriteNum -- dot syntax
=
the spriteNum of me -- verbose syntax
=
the spriteNum of the sprite to which this particular instance of the behavior is attached.
-- English sentence phrasing

Using parameters that are assigned by the user

It is often useful to write scripts that allow the user to assign the value to the parameters. For example, if we wanted a script that tells Director to wait a certain amount of time, the amount of time could be parameter defined by the user. We could write it in the following scripts.

Movie script
-- Wait a certain amount of time
on wait numTicksToWait
  startWait = the timer
  repeat while (the timer - startWait) < \
numTicksToWait  
    -- keep other action going on stage during repeat
    updateStage
  end repeat
end

The above is a movie script that uses numTicksToWait as the user assigned parameter. We could then create the following behavior.

Frame behavior
on exitFrame me
  wait 10*60
end

The frame behavior above, uses the custom handler wait and then assigns a value of 10 seconds (10 multiplied by 60 ticks) to that parameter. We could reuse the wait handler in a number of situations each time assigning a new value.

It is better to use milliseconds over ticks, which guarantees greater reliability. The script could:
-- Wait a certain amount of time
on wait pNumMilliSecondsToWait
  startWait = the milliseconds
  repeat while (the milliseconds - startWait) < \
numMilliSecondsToWait 
    -- keep other action going on stage during repeat
    updateStage
  end repeat
end

The wait custom handler allows our parameter to be user-defined but it involves writing a new script to give the value to the parameter. If we wanted to make this as easy as possible to use by a non-programmer (or any dummy), we could create a parameters dialog box, like the ones that appear when using the behaviors in Director's library.

The above script is is problematic. It keeps Director in a repeat loop for a significant amount of time combined with updateStage, making it very CPU intensive. If you run the behavior in this way, you'll see it won't play well. So, I'm going to change this slightly when I convert it to a behavior with user assigned parameters, as seen below:

-- define properties
property pNumMilliSecondsToWait, pStartWait

-- set the start time at the start
on beginSprite
  pStartWait = the milliseconds
end

on exitFrame
  wait pNumMilliSecondsToWait
end

-- wait custom handler
on wait pNumMilliSecondsToWait
  -- loop in the frame until time is up
  if (the milliseconds - pStartWait) < \
pNumMilliSecondsToWait then go the frame
end

on getPropertyDescriptionList
  pList = [:] -- creates an empty property list
  addProp pList #pNumMilliSecondsToWait, \
[#comment:"Number of milliseconds to wait:", \
#format: #integer, #default:"1000"]
  return pList
end

When the above behavior is dragged onto a sprite or into a frame, you will see a dialog box that asks for the Number of milliseconds to wait. The behaviors become more flexible and easier to use by prompting the user for the parameter value of pNumMilliSecondsToWait as soon as it is applied. I have added the 'p' to the parameter name to identify it as a property.

We created the dialog box using the getPropertyDescriptionList handler. In this handler, we create a property list, which I have called pList (following the naming convention of adding 'p' as a prefix to property items). The list contains the following:
#comment is used for the description of the parameter in the dialog box that will appear
#format is the value type of the parameter, which in our case is an integer #integer
#default is the value that appears in the dialog box when it first appears

For more detail on creating a parameters dialog box, see the Creating Parameters Dialog Box Technote.