<title></title>

<div class="article">

<p>A variable is a place to store a <i>value</i> in computer memory. You could think of a

variable as a cardboard box. You can put an object inside the box, shove the box into a closet, then

eventually dig it out again and retrieve the item. Usually, people put a label or other kind of marker on

the outside of the box to remember what's inside.</p>

<p>Variables work the same way: each variable has a <i>name</i> and a <i>value</i>. The name is like the label on a box – a shorthand reminder of what the variable "contains". The value can be any piece of information your PlotDevice script needs to remember: an important number, a piece of <a href="Strings.html">text</a>, a <a href="Collections.html">list</a> of colors, and so on.</p>

<!-- <p>Another way to look at variables is to think of them as sticky notes.</p> -->

<!-- <h2>Where do variables live?</h2> -->

<p>Each script has its own memory storage for variables – a private warehouse of boxed-up values and labels. The

specific value of a variable is therefore only known inside the script where it is used, not in

other scripts.</p>

<h1>Using Variables</h1>

<p>You store things in variables when you plan to <b>reuse</b> them. If you're going to draw a dozen rectangles

where each one is a hundred pixels wide, it’s a good idea to declare a <i>width</i> variable that stores the number <i>100</i>. You can then the rectangles look at what’s inside the <i>width</i> variable (rather than typing the same <a href="http://en.wikipedia.org/wiki/Magic_number_(programming)#Unnamed_numerical_constants">magic number</a> in every call to the <i>rect()</i> command).</p>

<p>This way, when you change your mind about the rectangles' width, you only need to change the contents of the <em>variable</em>, since each rectangle is looking there for its width. This is an example of <a href="http://en.wikipedia.org/wiki/Indirection">indirection</a>, a key concept in computer science.</p>

<h2>Declaring variables</h2>

<p>You can create a new variable at any point in your script and give it <b>any name you like</b>, though you should try to stay away from names that PlotDevice has already claimed (like <i>rect</i>, or <i>for</i>). It's best to pick a name that tells you something about the kind of information the variable is storing.</p>

<hr>

<p class="double-dagger">Try to come up with short, descriptive names. No one is happy about having to type <code>theWidthOfAllTheRectangles</code> dozens of times; especially when a simple name like <code>width</code> says enough.</p>

<hr>

<p>Once you've chosen a name you can "assign" any value you like to it with the "<code>=</code>" operator. You can then use the variable as a stand-in for the value when calling commands:</p>

<div class="example">

<span><img height="135" src="../etc/tut/variables-boxen-01.png" width="242"/></span>

<p><em>When you declare a new variable, PlotDevice sets aside a metaphorical storage box with a label to remind itself which variable "contains" the new value.</em></p>

<pre>

width = 100

rect(10, 10, width, 30)</pre>

</div>

<h2>Changing variables</h2>

<p>You can change the value of a variable over the course of a script. When this happens, the old value is thrown away and the variable now contains the new value.</p>

<div class="example">

<span><img height="185" src="../etc/tut/variables-boxen-02.png" width="242"/></span>

<p><em>The first rectangle is drawn when the <code>width</code> value is 100. We then change <code>width</code> to 20 and draw two more rectangles (which use the newly-set value).</em></p>

<pre>

width = 100

rect(10, 10, width, 30 )

width = 20

rect(120, 10, width, 30)

rect(330, 10, width, 30)

</div>

<h2>Calculations with variables</h2>

<p>When you store numbers in variables you can perform calculations as though the variable <em>were</em> the actual number. To perform basic "calculator arithmetic", you can use the <code class="kw">+</code>, <code class="kw">-</code>, <code class="kw">*</code>, and <code class="kw">/</code> operators. You can also assign a new value that's <b>based on</b> the variable's current value by using one of the <a href="http://en.wikipedia.org/wiki/Augmented_assignment">augmented assignment</a> operators:</p>

<div class="example">

<span><img height="303" src="../etc/tut/variables-boxen-03.png" width="242"/></span>

count = 10

print("half of", count, "is", count/2)

>>> half of 10 is 5

count += 5 # equivalent to: count = count+5

print(count)

>>> 15

count *= 3 # equivalent to: count = count*3

print(count)

>>> 45

</div>

<p>This comes up quite frequently when laying out sequential blocks of text since the lines' positions aren't truly independent. Ideally, paragraph text should go neatly below the title (and when the title font size changes the paragraph text should move along to match it).</p>

<p>Another way of saying this is that the paragraph’s vertical position should be calculated <b>relative to</b> the title’s vertical

position. In this example we use the <code>y</code> variable to position the title, then update its value to reflect the title's measured height:</p>

<div class="example">

<span><img height="85" src="../etc/tut/variables-math2.jpg" width="222"/></span>

<pre>

x = 30

y = 30

quote = "Nicely on the left"

text(quote, x, y)

y += measure(quote).height

quote = "Nicely below each other"

text(quote, x, y)

</div>

<h1>Predefined Variables</h1>

<p>PlotDevice has a set of predefined variables that contain information about the state of your

script. These variables can only be looked at, not modified.</p>

<ul>

<li><code class="kw">WIDTH</code>: the width of the drawing area

</li><li><code class="kw">HEIGHT</code>: the height of the drawing area

</li><li><code class="kw">PAGENUM</code>: the current page in a multi-page export.

</li><li><code class="kw">FRAME</code>: the current frame in an <a href="Animation.html">animation</a>.<br/>

</li></ul>

<p>Other variables can be used to create interactive animations:</p>

<ul>

<li><code class="kw">MOUSEX</code>: the horizontal location of the mouse cursor

</li><li><code class="kw">MOUSEY</code>: the vertical location of the mouse cursor

</li><li><code class="kw">mousedown</code>: is True when the mouse button is pressed, False otherwise

</li><li><code class="kw">keydown</code>: is True when a key is being pressed, False otherwise

</li><li><code class="kw">key</code>: the last key pressed

</li><li><code class="kw">keycode</code>: the integer keycode of the last key pressed

</li><li><code class="kw">KEY_UP</code>, <code class="kw">KEY_DOWN_</code> <code class="kw">KEY_LEFT</code>, <code class="kw">KEY_RIGHT</code>, <code class="kw">KEY_BACKSPACE</code> contain the keycodes for the arrow

keys and the backspace key.

</li></ul>

<p>You can see the full list of global variables PlotDevice maintains for you in the reference section on <a href="../ref/Misc.html#Constants">Constants</a>.</p>

<h1>The Variables Panel</h1>

<p>The variables panel displays script variables visually as sliders, fields, or check boxes.

When you drag a variable's slider, its value changes on the fly and will affect the output in the

drawing area. <!-- Any <a href="../ref/Misc.html#random()">random()</a> values in your script are

<div class="media"><img height="490" src="../etc/tut/variables-panel.png" width="760"/></div>

<p>You can add user-controlled variables to the panel with the <a href="../ref/Misc.html#var()">var()</a> command.</p>

<pre>var("name", NUMBER, value, min, max, step)</pre>

<pre>var("name", TEXT, a_string)</pre>

<pre>var("name", BOOLEAN, true_or_false)</pre>

<pre>def do_something():

print("i did it!")

var('do_something', BUTTON, button_text)</pre>

<p>You can then use the <i>name</i> variable in your script like any other variable. Numbers

produce a slider, text an input field and booleans (<i>True</i> or <i>False</i>) a checkbox.

The <i>name</i> parameter for buttons doesn't actually create a variable—instead you use it to identify a function

that you've defined in your script that should be called when the button is clicked. The button will have the name of your

function as its text label unless you pass an alternate string for it to use as the third argument.</p>

<p>By default, the variables panel will label each of your controls using the same name as your variable, but if you provide

a <i>label</i> argument, you can customize it. The <code class="kw">BUTTON</code> type also allows you to specify a <i>color</i>

value for it to use as its background:</p>

<pre>var("surname", TEXT, "Richelieu", label="Last Name")

var("search_geneology", BUTTON, "Search", label="Find Relatives", color="#f00")

<p>The variable panel is modeled on <a href="http://bob.ippoli.to">Bob Ippolito’s widget drawer</a> in the

original DrawBot.</p>

</div>