LiveCode Mobile Development Beginner's Guide

In addition to the document window itself, these are the main windows that we will need to be familiar with for now:

The upper area of the Tools palette shows all of the interface controls that you will need to create an interactive application. Below them are a set of tools for editing vector graphics, and a set of tools for editing bitmap graphics.

The Inspector palette shows all of the options for the control that you currently have selected. In the above screenshot nothing is selected, and so the Inspector palette is showing information about the stack itself.

The Message Box is a window that lets you try out either single or multiple lines of code. You will be able to invoke functions in your stacks too, making it a very handy way to test individual functions while you are tracking down issues. We'll use the Message Box in later chapters.

As suggested above, you should read the User Guide to get a deeper understanding of these windows, but let's try putting together something simple for now, to get you more familiar with using the Tool palette.

Hopefully you will have made a random bunch of interface controls, perhaps some that are nicely lined up too! Now delete them all, and get ready to make the simple calculator interface.

But first we should go over some of the structure and hierarchy of a LiveCode stack, and also create some basic navigation.

As described in the Background history and metaphors section of this chapter, LiveCode uses a stack of cards metaphor. When you make a new stack you, in effect, have a single-card stack of cards. However, even the simplest application is likely to have more than one card. For example, there could be a splash screen, a title card, cards for the actual task at hand, and a credits page. In the calculator stack we will use two cards. The Tools menu includes an option to view the structure of the stack, by showing the Application Browser:

In programming languages like the one in LiveCode, code is referred to as scripts, while methods or functions are known as handlers (though in LiveCode a handler that returns a value is also called a function). Projects made with harder-to-use programming tools often consist of dozens of external text files, one for each model, view, or controller. In LiveCode this is simpler; the scripts are attached to the object that needs that code.

To deal with user interaction in other tools you will have to write code that receives the event (perhaps just a mouse-click on a button), and to then perform the relevant action. In LiveCode there is a message path that takes care of these events and passes them up the hierarchy. If you click on a LiveCode interface control that doesn't have a mouse event handler, the click goes up the hierarchy to the card level. If the card doesn't have a handler for that event, it continues up to the stack level.

You can have additional levels of hierarchy, by putting other stacks into use, but for our purposes we just need the button, card, and stack hierarchies.

This message hierarchy allows us to place the code needed by several interface controls into a higher level, available to all of those controls. One such case will be with the calculator's number buttons; each one needs to do exactly the same thing, and by putting that code into the card level, each of them can make use of that single handler.

There is no performance advantage to having the shared handler in the card level, or much of a file size improvement, but as you are developing the code for the simple calculator, you can make changes to the single card script, instead of 11 individual calculator button scripts.

We will now start to build the calculator, and add scripts to the 14 buttons, a field, and the card.

That may have seemed like a lot of steps, but we did create the two cards we need, laid out a nice looking title field, and created a Begin button with its own script. In reality those steps take under two minutes, and even less as you gain experience in LiveCode.

If you want to make it big in the multimedia authoring tool world, which of these names would be a bad choice?

You will find yourself using the Inspector palette a lot, so take a moment to study how it behaves. When you select an object on the card you will see that the Inspector palette changes its appearance, sometimes even its height, to show the options for the item you have selected. It is smart enough to notice when you have selected multiple items, and will then show the align tools.

Sometimes you will want to keep an Inspector palette set to view the options of a particular object on the card, and to not switch to show a different object as you make other selections. In the upper right-hand side corner of the Inspector palette is a padlock icon, which will let you lock the inspector to the current object.

So far, most of the Inspector palette options haven't affected us, but one that is about to be relevant is the fact that you can set a name for an item that is different to its label. You may know from other programming languages, and this also applies to LiveCode, that some names are less legal than others. Perhaps you can't have spaces in the name, or use a colon, or backslash. If you name a button with a number, Button "1" may not be Button 1, and that could lead to confusion.

For the calculator keys we will set a label to make it look correct, and a name that doesn't lead to confusion. Speaking of those calculator keys…

Quite a lot just happened! We have now made all of the card level objects, and typed in their scripts. Most of the scripts are "calling" up to a card level handler that we will be setting up next. Before we do that it's worth trying to understand some of the lines we just entered.

The near-English nature of the programming language in LiveCode is amazingly powerful, but rigidly so. In some other tools you have a choice of whether you use verbose English-like syntax, less verbose, or what is called dot syntax. The Lingo language, in Adobe Director, is a good example to compare to.

Suppose we want to change the text inside a field that is the first entry of a Director movie's cast, we can use verbose syntax:

put "hello world" into the text of member 1 

or slightly less verbose syntax:

the text of member 1 = "hello world"

or dot syntax:

member(1).text = "hello world"

In LiveCode there isn't that choice - what you type has to be in the form of:

put value into container

You do have a choice about whether you use a long version of a word, a short version, or an abbreviated form. There are also synonyms, which allow you to use a word that makes more sense to you.

Here are two ways of saying the same thing, with the second variation using an abbreviated form of the key words:

put character 3 of word 2 of card field "name of field 1" into aVariable

put char 3 of word 2 of fld 1 into aVariable

When you are dealing with the contents of the object that has the script that is running, you can use the keyword me to save on some typing, and LiveCode will also try to work out what you have in mind, if possible.

Take the lines we have entered as examples:

numberPressed the label of me

numberPressed will propagate up to a card handler we will add (soon). the label of me will look at the Label that you set for the object that the script is inside of.

set the clipboarddata["TEXT"] to me

In this case, me would normally refer to the object (as is the case with the label of me), but because we gave the extra clue of ["TEXT"], LiveCode knows that it's the text contents of the field that has that script, and not the field itself. Still, because there is the potential for confusion when reading your own code later, you could add a couple of words to make the meaning more clear:

set the clipboarddata["TEXT"] to the text of me

You might choose to be more verbose than is needed, just for readability reasons, and in these chapters that is going to be the case. Using:

put the text of me into textvariable

makes it easier to tell what is going to happen than if you use the equally valid:

put me into textVariable

In either case, as it's a field, LiveCode knows what you meant.

Now look at the script in which we typed short name of me - what's that all about? Objects in LiveCode have a lengthy description of where they are located, e.g. "button "buttonname" of card id 1234 of stack "path/to/stack.livecode"". In the calculator application we need only the single word you set as the name of the button. If we asked for name of me, it would still say button "buttonname". To just grab the name itself, we use short name of me.

There are times when you will want to use the other variations of "name", including the long name and the abbreviated name, which you can read about in the LiveCode Dictionary entry for "name". In addition to a description of the different ways to use "name", there are a number of cautions shown.

If you had dared to try using the calculator buttons, you would have seen a lot of script errors. We need to add in the card level handlers to be at the receiving end of the calls that the buttons are making. Instead of walking you through typing one line of code at a time, it would probably be quicker to present the lines in one go and explain what each line does. As a practice run, here are the lines that we have entered so far:

On all of the number buttons and the decimal point button, you should have this script:

on mouseup
   numberPressed the label of me
end mouseup

on mouseUp is triggered when you press and release the left mouse button while on the button, numberPressed will call a card handler named "numberPressed", passing with it the Label that you had set for the button that holds this script.

The C (clear) button has this script:

on mouseUp
   clearPressed
end mouseUp

clearPressed will call a card script named "clearPressed"

The other buttons all work in much the same way - they call a handler of the name used, which we're about to add to the card script. The following is the script for the +, -, *, and / buttons, passing the name of the button in question to the card level:

on mouseUp
   operatorPressed the short name of me
end mouseUp

And this is the one on the +- button:

on mouseUp
   toggleSign
end mouseUp

The display field has this script:

on mouseUp
   set the clipboarddata["TEXT"] to me
end mouseUp

In the case of the field, it's only processing one line of code, so no need to put that up on the card level, unless we had a lot of fields doing the same thing.

So, why don't we add all those card level scripts? Here they are, one at a time, with an explanation of how each one works:

But wait… we haven't yet talked about variables. Hold that thought, while we see how LiveCode handles variables.

Generally speaking, variables are memory locations where you store values that you need to access later. In most programming languages you can dictate which routines have access to which variables. Less English-like languages may use the terms "public", "private", and "protected". Things are not all that different in LiveCode but here the words used describe more the region where the variable can be used. If a variable is to be readable everywhere, it would be "global". If it's just to be used in the current script, it's "local".

LiveCode also has custom property variables, and many people would use those for the calculator button values instead of relying on the label of the button. We'll perhaps use them later!

Now, where was I… oh yes, card level scripts:

This is the first line of the card script:

global currenttotal,currentvalue,currentcommand,newnumber

As we just discussed, these are variables that will allow all of the handlers to pass values to each other. In this case the variables could have been local, but you may often decide to use global instead, thinking that a case may come up later where you need to access the variables from outside the script you're in.

It's good to reset things when you first start, and LiveCode has an opencard event that we can use to do this. The following code resets things:

on opencard
   clearpressed
end opencard

on clearpressed
   put true into newnumber
   put 0 into field "display"
   put 0 into currenttotal
   put 0 into currentvalue
   put empty into currentcommand
end clearpressed

Having the reset lines in the clearPressed handler will allow us to call it at other times and not just when the card opens. We can call it directly when clicking on the C (clear) button which will zero out the display field, the running total for your calculation, and the last number that you entered into the calculator. It also clears the variable that is used to remember which operator button you last pressed, and a boolean (true/false) variable used to recognize whether a number button you press should clear the display or append to the display.

All of the numbered buttons, and the decimal point button, call this handler:

on numberPressed n
   if newnumber is true then
      put n into field "display"
      put false into newnumber
   else
      put n after field "display"
   end if
end numberPressed

The n after the handler name is a parameter variable that stores what was sent to the handler. In this case it's the label of the button that was pressed. All this routine needs to do is add the character to the end of the display field, except for when you are typing in a new number. That's where the newNumber boolean variable comes in - if that is set to true, the incoming character replaces the contents of the display field. However, if it's false, the character is added to the end of the field.

This is the handler for when you press the +, -, *, or / buttons:

on operatorPressed operator
   if currentCommand is empty then
      put field "display" into currentTotal
      put operator into currentCommand
      put true into newNumber
   else
      put operator into currentCommand
      equalsPressed
   end if
end operatorPressed

When you use a calculator, you type in a number, an operator, and then another number, followed by either another operator or the = button. At the time you press the operator button there is no way to know the result, as you haven't yet entered the next number in the calculation. So, we remember the operator till you have entered the next number. If the currentcommand variable doesn't already have a value, we store the display field text into the currenttotal variable, the operator character that you pressed into the currentcommand variable, and make sure that newnumber is set to true. Doing this makes sure that the next number button you press will clear the display field. If currentcommand already has a value, we replace it with the new value, and then call the same handler that is used when you press the = button.

There are most likely shorter ways to deal with the = button being pressed, but here we'll use several if statements, and run the appropriate calculation code:

on equalsPressed
   put field "display" into currentValue
   if currentCommand is empty then exit equalsPressed
   if currentCommand is "divide" then put currentTotal / currentValue into field "display"
   if currentCommand is "multiply" then put currentTotal * currentValue into field "display"
   if currentCommand is "minus" then put currentTotal - currentValue into field "display"
   if currentCommand is "plus" then put currentTotal + currentValue into field "display"
   put field "display" into currentTotal
   put true into newNumber
   put empty into currentCommand
end equalsPressed

The contents of the display field are stored in the currentValue variable , and the last operator button you pressed (that is stored in currentCommand) is looked at, to see what happens next. If there wasn't a previous operator (as would be the case if you pressed = twice in a row) we ignore the button press and exit the routine. For the four operators, we do the appropriate calculation. Afterwards, we store the new running total into the currentTotal variable, make sure that the newNumber boolean variable is set to true (so that the next number button pressed will clear the display field), and we forget the last operator button that was pressed, by putting empty into the currentCommand variable.

One thing to note is that LiveCode is smart enough to know that the text string inside the display field is to be treated as a floating point number.

For the last handler, togglesign, insert the following code:

on togglesign
   if character 1 of field "display" is "-" then
      delete character 1 of field "display"
   else
      put "-" before field "display"
   end if
end togglesign

This is a very simple routine, that doesn't have to understand that it's floating point numbers being represented. It simply looks to see if the first character is a minus or not, and if it is, it deletes the character. If not, it inserts the hyphen that LiveCode will later interpret as a negative value.

As you get to learn a new tool you can end up taking a lot of time remembering where the thing is that you need. You know what you want to do, you know how to do it, but you can't remember where that thing is located! Where did you go to set the text styling for the calculator's title field?

It is possible to add more features to the simple calculator. If we consider how the buttons are named, and the functions in the card script, you can start to see what would be involved in adding a new ability:

On Windows you can make a square root symbol with Alt+251, and on Mac with Option+v. Unfortunately LiveCode doesn't like those as button labels! At least on Mac, when you type that character into the Inspector palette, the character immediately vanishes. One work-around would be to use the message box, and type this:

set the label of btn "squareroot" to "√"

That should give you the right symbol as the button label.

LiveCode has a square root function; typing this into the Message Box would produce the square root of 10:

put sqrt(10)

Now, armed with the above information, try to add a square root feature to the calculator.

If your system has QuickTime installed, LiveCode can play QuickTime movies, using the Player control type. Those can be added to the card in several ways, as well as by using a script command as described in the following points:

Having added the player to the card, you can then set which video file is to be played by entering the file path or URL of the file under the Basic Settings of the Inspector palette. You can also set the path to the video with the following script:

set the filename of player "player name" to "file path or URL"

In the same way that you just saw for playing video, still images can also be added to a stack. All of the options shown for adding a video player can be used for images. Here, for example, is the script needed to add the RunRev company logo to the card:

new image "revlogo"
set the filename of image "revlogo" to "http://www.runrev.com/runrev-globals/corporate-nav/images/runrev.gif"

Images that you import can be used as icons in a button. To set up a button so that it has a nice idle state image, and an associated highlight image, you would do the following steps:

Here we can see two images that have been imported in order to give the Begin button a more iOS appearance. The button is selected, and the Inspector palette shows the icon selection choices.

Then when you choose an image to use, the button itself will be updated. In this case the Hover Icon has been set to the darker version of the graphic, but as shown here, the button still needs to be resized.

LiveCode has a lot of different controls. Many are just slight variations, but there are plenty that are quite different from each other. Look at the Object menu, and then New Control. As you'll see the list is very long!