----------------
Variables:
----------------

What is a Variable?    
A variable is a container for information that will change. It can allow Director to remember and use information for short or long periods in a Director movie.

In the variables we will look at and use here, you can only have one piece of information in a variable at a time. 

Variables that can hold more than one piece of information at a time are called list variables, and are covered in my page about lists. However, list variables also follow all the rules below...

----------------
Variable Name Rules:   
----------------

    * Variable names can be almost anything. You make the name up.
    * They can't have spaces or punctuation in them.
    * Variable names can't be names already used for other things in Lingo syntax.
    * Use letters for variable names (along with numbers, if you wish), but not numbers by themselves.
    * Make sure all your variables names start with a letter.
    * No two variable names in a project should be the same.

In recent versions of Director, colour coding is evident in script windows, which helps you to distinguish 
scripting commands from other things by colour. This is useful, because you can check the colour of the names 
of variables to make sure they are not already Director commands. Variable names should show up black 
in the scripting window. If your variable name turns any colour other than black (it could turn green or
 blue, for instance) you need to change the variable name because it is already the name of a scripting term or command. 

----------------
Local Variables and Global Variables:
----------------

local variables - short remembering - used only for the duration of that script 
global variables - long remembering - used to store/remember info longer, or so the info can be used
 anywhere in a movie

----------------
Local Variables:
----------------
Any variable _not_ declared to be global is understood to be local the when you use it in a script.
Local variables often just help you get something else done in a script, and may not require a lot of thought for use.

For example, this is a local variable: x

x = random(2)

if x = 1 then
 -- do something
else if x = 2 then
 -- do something else
end if


----------------
Global Variables:
----------------
Declare the variable to be global if you need the information in it to be used in other scripts or in other parts of the movie. Global variables are what enable you to remember events, settings or information.

Declare the variable to be global at the start of each script you are using it in.

If my global variable's name was purpletupee, then I'd declare it to be global like this:
on mouseUp me
 global purpletupee
 -- lines of script
end

OR like this, for several global variables:
on mouseUp me
 global firstglobalv, secondglobalv, thirdgvariable
 -- lines of script
end


How long are global variables remembered?
- throughout the whole movie
- remembered even if you press stop in director
- remembered even if you open a new/different movie in director and play it

- all global variables are remembered UNTIL you:
   a) quit director
   b) crash director/shut off the computer
   c) use a clearglobals command in a script or message window
   d) reset the variable using commands in a script

So you need to know how to clear or reset global variables.


----------------
Powerful Global Variable Commands: Lingo syntax
----------------

showglobals   -- if you type it in the message window, 
and hit return, it shows all global variables currently being remembered
(you may be surprised at what shows up)

clearglobals  -- if you type it in the message window,
and hit return, it erases all global variables 


The Message window:

To make SURE your movie with global variables is working CORRECTLY:

1- Use the clearglobals command in the message window
2- Rewind your movie and start it playing from the start
3- If it works perfectly, then it should be good! If not, then you've got an error somewhere 
in your scripts with global variables.

If you do not take the steps above, the danger is that your own project might be missing some 
scripting to set up global variables, but you won't know it. Often, people play an example
movie from Don or me (Nadine), and then play their own movies -- and if they have used the
same global variable names as in the example movie, there is nothing to show whether their
own movie is setting up the global variables properly or not. The only way to know is by going
through the above 3 steps, and seeing if their own movie still works perfectly. 


----------------
To See What is in Your Global Variables:
----------------
Either:
- use the showglobals command again and again in the MESSAGE window
(this option can get too repetitive)

Or:
- use the OBJECT INSPECTOR (like the Message window, it can be found under the Window menu)
(this option is good for continuous display of what is in the variables)

Using the Object Inspector to SEE what's in your global variables:
 - Double-click under the Name column, and type in your global variable's name
 - Then in the Value column, you will see what is currently in that variable
 - Type in the name of each of your global variables, so you can monitor them.


----------------
Some Example Scripts
----------------
Using a global variable to get the user's name, and then use it in a different section called "nextscreen":

on mouseup
  global uname

  uname = member("textentry").text 

  if uname ="" then
    _player.alert("Please type your name!")
  else 
    _movie.go("nextscreen")
  end if

end

---
What setup and script are needed in the "nextscreen" section to display the user's name in a new text cast member? 

1) a brand new text cast member on the stage
2) a new button on the stage
3) - when you click the button, the text cast member on the stage displays the message "Hi!" and whatever the user's name is (use concatenation).


The script part of the solution to the above:

on mouseup
  global uname

  x = "Hi " & uname & "!"
  member("display").text = x
end

---