Resources

How LiveCode menus work

A LiveCode menu consists of a set of popdown buttons, grouped together, and placed at the top of the card. The menu items that appear in each menu are just a return-delimited list stored in the button contents. The behavior of each menu is governed by the menu group’s script.

On a Macintosh, if a menu group is not placed on a card, no stack menus appear in the Mac menu bar while that card is current. (There is one exception. It is possible to assign a default menu bar that appears when no other menu group is available. The default menu bar is only effective on Macs; if run on Windows, the stack will not have a menu on that card.) If a stack with no menus is run in the IDE, LiveCode’s developer menus will appear instead. If the stack does have a menu, then its own menus will replace the IDE menus. In the IDE, the developer menus can be accessed by bringing the message box, tool palette, or other native LiveCode stack to the front.

If a stack with no menus is run in a standalone, the Mac menu bar will be empty except for the default Apple and Help system menus.

On Windows machines, LiveCode’s developer menus are displayed in a palette and none of the above applies since there is no system menu bar. A card either has a menu or it doesn’t.

LiveCode menus are objects that take up room at the top of a card. On Windows and Linux, this is standard; menus appear at the top of each window. When the same stack is run on a Mac, LiveCode scrolls the top portion of the card above the top border of the window, out of view, and translates the menus to the system menu at the top of the screen. The body of the window shortens to accomodate only that portion of the card that contains the actual stack content. The card is still technically the same height, but the area that contains the menu group is hidden. LiveCode handles this window resizing transparently between platforms.

The easiest way to create a menu bar is to use the Menu Builder, located in the IDE’s Tools menu. On a Mac, you can see how the menu display works there. After creating a menu bar, tick the checkbox “Set as stack Menu bar” (which sets the editMenus property) to see how the menu portion of the stack is scrolled out of view and the window height is shortened to accomodate. This setting should be turned on if you will distribute to Mac users. On Windows, it is ignored.

EditMenus false

EditMenus true

Best practice is to create the menu bar first, before any other controls are placed. Because menus take up space at the top of the card, at least a basic group should be created before anything else; you can always edit it later. If the menu group isn’t there from the beginning, you’ll probably have to move all other card objects downward and increase the stack height later to accomodate the menu group.

During development it’s easiest to leave the menu visible in the window, and wait to apply the editMenus property (“set as stack menu bar”) until deploying to Mac. If the menubar is not visible on the card, what appears to be coordinates “0,0” on a Mac screen will really be more like “0,29”, because the first 29 pixels contain the menu group hidden above the top of the window. Any scripts that work with card coordinates need to account for that. This is most easily done by creating the menu bar early on and laying out all controls while the menu bar is visible in the stack window. That way you can be sure that no controls will scroll off the top on a Mac, and all scripted coordinates will be correct regardless of the deployment platform.

For more information about LiveCode menus, see the editMenus, defaultMenuBar and menuBar properties in the dictionary or the User Guide.

How To Test Your Stacks

(or) Gee, It Doesn’t Do That On My Machine

by Jacqueline Landman Gay
HyperActive Software

There is one single thing that defines a top-quality application: everything works. This may sound simplistic, but it’s the bottom line. It doesn’t matter how slick your user interface is, or how tricky the scripts are, or how sophisticated the material you are presenting; if everything in the project doesn’t work exactly right, your work will be ignored—or worse, scorned—by others.

There’s no secret to creating a great application that people will use and enjoy. Test the application and everything in it, again and again. Run everything through its paces several times and in different orders. Click every button, read and scroll every field, run every script. Show every dialog—and when you do, try every possible response button. Then get all your friends to do the same thing too.

That’s it. Everything else I’m about to tell you is just commentary.

Most application errors and mistakes can be prevented by using a few simple testing techniques. Unfortunately, too many authors don’t want to take the time to test their work adequately. While the fun may be in designing and scripting an application, remember that everyone else’s opinion of it will be based on its performance. Users have high expectations of software these days, and they won’t take time to figure out work-arounds to glitches. They’ll just toss your application in the trash instead. Worse yet, they may avoid your work in the future based on one bad experience.

Try the following tips before releasing your stack. You may be surprised what you find. These techniques should ensure that your stack is as bug-free as it can be.

1. Pretend you just met your application in a crowded library and you don’t know anything about it. Start clicking on (or typing into) everything. This doesn’t just mean using the obvious buttons; it means, for example, clicking on locked fields that have scripts, and using all dialog boxes. Repeatedly bring up every dialog box until you have tried all possible responses to it, and don’t forget “cancel”, you need to account for a user wanting to bail out. Don’t forget any controls that are hidden right now but that might be visible and used later; activate and use those too. Every button should do exactly as it is labeled (so choose your button names carefully.) Every script should interact cleanly with everything else without causing any errors. Click outside any buttons or fields, right on the card itself, to be sure that nothing unexpected happens. If you’ve created any menus, systematically choose every single menu item, one at a time, to be sure it behaves right.
2. Set up some fake data with known content and test with that. Say you have a stack that opens a text file of numbers and totals them. Set up a text file and get a total with your hand calculator. Then run your application on the file and see if you get the same results. Or suppose you have a script that counts the number of times a text string occurs in another stack. Set up the other stack with a known number of repetitions of some text and then see if your script returns the right number. Too often scripters will suppose that if the script doesn’t error when it runs, it must be okay. All that means is that you haven’t any syntax errors; it doesn’t say anything about the accuracy of the results when the script is done. Do tests on several different sets of known data. One set isn’t enough; you need to account for all types of variation. In the first example above, you might create a text file containing all numbers except for one line of text. What happens when you run your script on that?
3. Once you’ve tried everything, and I mean everything, go back and try it all over again in a different order, preferably the wrong order. This will be incredibly educational. Don’t fool yourself into thinking that your users will click all the buttons in the correct order, or even in any logical order (although your stack must present everything in an orderly way.) For example, what happens if a user decides to push a “calculate” button before they enter any data into some number fields? Does the app exit gracefully? Or does it error out half finished and leave the stack in an unpredictable state? What happens if users enter letters and other symbols that aren’t numbers, or type in numbers in the wrong range (always test-enter numerical data as negative numbers at least once.) What happens to your other scripts when one script fails? Do you get a cascading failure when each succeeding handler looks for information that now doesn’t exist, or exists in the wrong format? Try your hardest to enter incorrect information into every field, enter data in the wrong format, and click every button out of logical order. While it is fine if this doesn’t produce any usable results, it should definitely not produce any script errors either. If it does, you haven’t done enough error-checking in your scripts. Don’t think to yourself, “my stack is aimed at Mensa members with IQ’s over 165 and they would never do that sort of thing, so I don’t have to check for it.” Trust me, they will. And you do. Whenever you repair a script, no matter how small the change, start the testing process over again. There’s no way around it; you have to be sure not only that the change in your script works correctly, but that it works correctly with everything else. You can use some judgment here. If you alter a script that displays information in a field, you probably only have to test that one script to be sure the display is correct. But if any other part of your application uses the data in that field later, then you need to re-test every other script that uses that field information. This may sound tedious, but it is the only way to avoid one of the main causes of errors: the interaction of different elements of your application.
4. Get three other people to run your application. This is hugely important. Never, ever release an application that no one else has used. If you don’t know three other people, at least get one. If you know more than three, go for as many as you can rope into it. No two people will use your application the same way. Certainly no one will use it exactly the way you think they will. What they do with your app will tell you worlds about your work. Choose people for testing who are as close as possible to the kinds of people who will be downloading and using your application. If your app is for children, use children to test it. If it’s for anthropology professors, find some of those. If you don’t know any anthropology professors then you can use your mother if you have to, but don’t expect her to find all the anthropology mistakes. She will, however, probably still find a lot of generic errors having to do with application design.
   Don’t tell your testers what to do. This is a strict rule. Let them read any documentation or Read Me files you will supply with your application, but that’s all. This is easier said than done, but remember that no one who downloads your software will have you around to give them verbal directions, and your tester shouldn’t get any either. So limit yourself to watching, bite your tongue, and take a lot of notes. See what actions they choose to do first, where they get stuck, and how they look around in the app for help if they need it (you did put some help info in there, right?) This will tell you where your design isn’t clear. Don’t offer any advice unless the other person asks outright, and in that case give as little information as possible to get them back on track. When they’re done, you can ask them questions from your notes if you need to. Ask what they thought was good about the application and what was not so good. Pay attention to what they say and change your app if necessary. Try not to decide that they “didn’t know what they were doing” and don’t dismiss their comments as irrelevant. If your testers can’t figure it out, probably no one else can either.
5. Run your stack on other people’s computers, the more the better. If you are distributing cross-platform, you must test on as many variations of your target platforms as you can lay your hands on. How do the fonts look? Does the text overspill your buttons? Is the window too big to show up fully on a small laptop screen, or does it diminish to a postage stamp on a 27″ monitor? How about speed? Is it acceptable on other computers? What flows smoothly on your state-of-the-art machine may stutter or crawl to a halt on an older one.
6. There’s one last way guaranteed to find every possible obscure bug, hiccup, and glitch in your application: demo the stack to someone else. No matter how much testing you’ve done or how many people have gone over your work, if there’s one obscure thing that can go wrong, it will gleefully manifest itself when you are trying to show your work to an important person—like a potential client, your latest love interest, or your anthropology professor. Those tiny little bugs that have been lurking under the paint layer just drooling for a chance to embarrass you will burst suddenly on screen, grinning and winking at each other. If you really, really want to find minute and obscure bugs, try showing off your software with as much pride as possible to someone important.
7. Avoid the “it’s my baby” syndrome. It is tempting, after spending a lot of time with a stack, to want to leave it just as it is, simply because it’s your baby. Be ruthless. Even babies are better for a little discipline. If something isn’t appropriate for your application’s purpose, take it out, no matter how cute it is or how much time you spent writing it. If your testers complain that fourteen repetitions of The Hamster Dance are a bit excessive, take it to the trash no matter how cute you think it may be. Remain constantly flexible. You don’t have to change everything your testers say (after all, they really might not know what they’re doing), but you should sure listen closely when they say it.

If you follow these testing guidelines, you can produce software that is consistently bug-free and reliable. The longer you test, the more people you test with, and the more repeatedly you test, the better your apps get. Even the simplest application can become pure art when it runs smoothly, behaves intuitively, and functions without errors.

LiveCode Functions

by Jacqueline Landman Gay
HyperActive Software

Using functions in LiveCode

LiveCode’s programming language is intuitive and easy to learn. It is very much like spoken English in some ways, and many commands can be written exactly as you would say them in natural language syntax. However, it is also a full and expansive programming language in its own right, and as such, it supports all the constructs that are found in any programming language. This includes two basic types of programming routines: command handlers and function handlers. Function handlers are usually referred to simply as “functions”.

Many LiveCode newcomers are not sure what the differences are between function handlers and command handlers. This document explains how functions work, and what the basic difference is between a handler that acts as a function and one that acts as a command.

What is a function?

A function is a handler that does some work and returns the results to the handler that asked for it.

Functions are distinguished syntactically in two ways; a function is called using either the keyword the or it is called using parentheses. You are probably using functions all the time in LiveCode and may not even know it. LiveCode has hundreds of built-in functions; for example, the date is a function (using the keyword the,) which can also be written date() using the parentheses form. When you use the date or date(), LiveCode does an evaluation and sends back today’s current date. This process happens invisibly inside the LiveCode engine, which contacts the OS, gets the system date, and returns it to your script. Then your script can use the date information to do some work.

Some functions need to know a bit of information before they can work; for example, the LiveCode function the number (also written number().) You need to pass a parameter to the function — some extra information — that tells it what you want to count, whether it is buttons, or cards, or graphics, or anything else. If we want to know the number of cards, we pass “cards” to the function this way:

the number of cards

which can also be written:

number(cards)

LiveCode then goes through the stack and adds all the cards to get a total, which is sent back to your script. Your script receives that value and needs to store it into a variable so that it can use it later:

put number(cards) into theNumCds

In this case, “theNumCds” contains a number, which is equal to the number of cards in the stack.

Writing your own functions

If LiveCode does not have a built-in function to do something you want, you can write your own function to do it instead. If your script uses a function you write yourself, the calling handler cannot use the when using it; the handler must use the parentheses form. Thus, a custom function called myFunction cannot be called with the myFunction — you must use myFunction() instead.

A note about the message path: The message path for functions is identical to the message path for command handlers. You should place your function at the level where any handler that calls it can use it. For example, if your custom function is used only by a single button, then an appropriate place for that function would be in the button script. If many buttons use the function, then it could go in the card script, a group script, or the stack script.

Suppose we want to add two numbers together and get a total. (This is a very simple task, but it makes a good example.) We can write a function called “addNumbers” like this:

function addNumbers num1,num2
  put num1 + num2 into theTotal
  return theTotal
end addNumbers

The parameters num1 and num2 are like baskets that hold whatever values the original handler sends. In this case, they will each contain a number. The special word return tells LiveCode to send the variable theTotal back to the handler that asked for the information. Note that whenever LiveCode sees the return keyword, the function will exit immediately afterward. This means that return is usually — but not always — the last line in the function’s script.

So, this function takes two numbers that are passed to it in the parameters, adds them together, and sends back a total. Now we can write a handler that uses the function:

on myHandler
  put field "firstNum" into theFirstNumber -- say the field contains 16
  put field "secondNum" into theSecondNumber -- say this one is 4
  put addNumbers(theFirstNumber,theSecondNumber) into field "sumTotal"
end myHandler

This handler will send 16 and 4 to our custom function addNumbers. The addNumbers function will catch these two numbers in its parameters num1 and num2, add them together, and send back 20. The handler myHandler will receive that 20 and put it into the field “sumTotal”. The field now displays 20.

When you use a function in a handler, you must provide a place for its results to go — a variable usually, or sometimes a field. For example, this will not work:

addNumbers(theFirstNumber,theSecondNumber)

because there is no place for the returned information to be stored. A handler that uses a function must provide a place to put the information that the function sends back. This is true of built-in LiveCode functions too. For example, this will not work:

the date

because there is no place to put the date that is returned. You must provide a place:

put the date into myDate

or:

put the date into field "today"

A handler that uses a custom function must follow the same rule. It must provide a place for the returned information to be stored:

put addNumbers(theFirstNumber,theSecondNumber) into myTotal

Here is another example. This one removes all vowels from a word and returns only the consonants:

on myHandler
  put getConsonants("chimpanzee") into field 1
end myHandler

function getConsonants theWord
  put "aeiou" into theVowels
  repeat for each char i in theWord
    if i is not in theVowels then put i after theChars
  end repeat
  return theChars
end getConsonants

In this example, the word “chimpanzee” is sent to the function getConsonants, where it is placed automatically into the parameter theWord. The function checks each character in the word and if it is not a vowel, it puts the character after a list called theChars. When it is finished checking each character, it returns the list of characters, which automatically gets sent back to the calling handler myHandler. The characters sent back in this example would be “chmpnz”, so that is what field 1 will display.

Functions can be as short or as long as you want, and sometimes can be very complicated. But the basics are always the same: a handler asks a function to do some work and often sends some parameters to the function to tell it what to work with. The function does the work and returns the finished calculation to the original handler. The handler can use the finished calculation any way it wants, just as if it were any other variable.

What’s the difference between a function and a command handler?

Not very much, when you get right down to it. They are both just a list of commands that accomplish something. The primary difference is that there is a built-in way for a handler to use the results of a function.

However, command handlers can also return results, in exactly the same way as functions do. The difference is in how the calling handler receives the result. When using a function, the result is sent back automatically and all the calling handler has to do is provide a storage place for it. When using a command handler, the calling handler must instead ask for the result specifically. We could change the addNumbers() function into a command handler by simply replacing the keyword function with the keyword on:

on addNumbers num1,num2
  put num1 + num2 into theTotal
  return theTotal
end addNumbers

Now that it is a command handler, the total that has been calculated is not sent back to the calling handler automatically. Instead, the calculation is placed in the system-wide storage area the result. The calling handler can retrieve the information at will by asking for the result:

on myHandler
  put 16 into theFirstNumber
  put 4 into theSecondNumber
  addNumbers theFirstNumber,theSecondNumber
  get the result -- this asks for the total
  put it into field "sumTotal"
end myHandler

Most of the time it is easier to just write the calculation as a function and allow LiveCode to send the result back automatically. However, the above is valid and in some situations may be preferable, though this author cannot think of any good examples of when this would be required.

Note that the result changes its value frequently and without warning, since a good many LiveCode commands use it to store temporary data — for example, the “ask” and “answer” dialogs use the result to store the name of the button the user clicks. If you will be retrieving the result from a command handler, it is a good idea to do so as soon after issuing the command as possible. If you allow too many lines of script to go by before retrieving the result, you may find that another command has changed its contents and the result no longer contains what you think it does.

Polling the Mouse in LiveCode

(or) How to wreck perfectly good software

by Jacqueline Landman Gay
HyperActive Software

A mouse() on a hamster wheel

A common scripting technique in any x-talk language is polling the mouse in order to get information about its state so that a script can perform an action. In HyperCard or SuperCard, for example, it is customary when simulating a dragging operation to use a repeat loop to get the mouseLoc in order to repeatedly set an object to the mouse location, or to check in a loop for a mouse condition to determine when to leave the loop. Here is a common example:

repeat until the mouse is up
  set the loc of btn "dragBtn" to the mouseLoc
end repeat

In MetaCard and LiveCode, this kind of mouse polling is emphatically discouraged. Scott Raney of MetaCard Corporation has this to say about the above repeat construct:

This loop uses 100% of the CPU time, regardless of the speed of the processor, bringing the system to its knees, causing poor feedback for your app, and making your system unresponsive to any other processes running on it. You see, on a fast system, 99.99% of the time through that loop you’re setting the loc to exactly the same coordinate!

I think the biggest problem here is that OSs have evolved way beyond the point where even developers (or at least most of our customers) understand how they work. There’s nothing wrong at all with things like “the mouse” on single-user single-tasking OSs like MacOS, but that’s just not the world we live in anymore…

I’m certainly sympathetic to the “easier way” and “programming for the rest of us” arguments, but none of us can afford to be classed as developers of system-hostile applications… Developing in a high level language will become a stigma that we’ll never live down…

Some of the processes that can slow down or stop when a script uses this kind of processor-intensive repeat loop are: file and printer sharing, HTTP/FTP servers, network management tools, and on UNIX systems (including Mac OS X), people telnetting in from other systems. Another problem on Mac OS X is the spinning rainbow cursor that may appear while the loop is in progress if the operation takes too long — the system puts that up whenever it thinks an application is unresponsive. That means if a user drags an object around the card for a while, or keeps the mouse button depressed for too long while the script is in a loop, the system may think your application has gone dead.

The problem is not limited to just checking the mouseloc or the mouse’s up or down state. Checking any of the following mouse events within a loop can cause a bottleneck and should be avoided:

• the mouse — i.e., “up” or “down”
• the mouseClick
• the mouseH
• the mouseV
• the mouseLoc

So what do I do?

You may be wondering at this point, “If I shouldn’t be using a repeat loop to determine the state of the mouse, what do I use?”

The answer lies in the mouseMove system message, sent by the MetaCard/LiveCode engine whenever the user moves the mouse. The mouseMove message carries two parameters with it: the horizontal and vertical coordinates of the current mouse position. By writing a handler that traps this system message, you can create an OS-friendly script that will not bottleneck the CPU and which will run far more efficiently than any repeat loop.

There is an additional advantage to using the mouseMove approach: it allows your stack to continue sending events and reporting other user actions simultaneously. Unlike a repeat loop, which locks out everything else until the handler ends, trapping a system message takes an insignificant amount of time and allows other system messages and all your stack’s features to continue operating at the same time. You may not always want to use the other messages that are being sent, but they are there if you need them.

How it works

In the above example, all we want to do is move a button to the same location as the current mouse position, for as long as the mouse button is depressed. If the mouse is “up”, the script should do nothing. A short handler in the button script could take care of it:

on mouseMove x,y
  if the mouse is down then set the loc of me to x,y
end mouseMove

Very easy. At the same time that mouseMove is catching the position of the mouse and handling the drag, you can also have other handlers running normally to catch various system messages or handle other events. You can think of mouseMove as a sort of customized, single-purpose idle message. (Note though that idle has its own set of processor-hogging problems, and should be avoided at all costs too.)

But wait. The mouseMove handler is still polling the mouse, checking for its down state repeatedly. So while we have improved the script’s efficiency, it is still using more resources than necessary. We can fix that by adding a variable that stores the state of the mouse, so that the engine won’t have to check it each time. We can set a flag on mouseDown, and turn it off on mouseRelease and mouseUp. While we’re at it, we’ll also add a line to the script that passes the ID of the object we are dragging so that more than one button can respond to the mouseMove message.

These handlers would go in the card or stack script:

on mouseDown
  global gDragging,gDragObj,gDeltaX,gDeltaY -- (you could use local script variables instead)
  if the name of the target contains "button" then
    put true into gDragging
    put the long id of the target into gDragObj
    -- the following adjusts for the mouse position on the object;
    -- it isn't part of what we're explaining here but it enhances the drag:
    put item 1 of the loc of gDragObj - the mouseH into gDeltaX
    put item 2 of the loc of gDragObj - the mouseV into gDeltaY
  end if
end mouseDown

on mouseRelease
  global gDragging
  put false into gDragging
end mouseRelease

on mouseUp
  global gDragging
  put false into gDragging
end mouseUp

on mouseMove x,y
  global gDragging,gDragObj,gDeltaX,gDeltaY
  if gDragging = true then
    add gDeltaX to x
    add gDeltaY to y
    set the loc of gDragObj to x,y
  end if
end mouseMove

Most HyperCard and SuperCard scripters are familiar with mouseDown and mouseUp, but mouseRelease may be new. The mouseRelease message is sent to an object when the mouse button goes up but the mouse is no longer within the borders of the object that received the original mouseDown message. This covers the case where the user may move the mouse faster than the button can keep up. Even if the mouse is released somewhere outside the button, this script will still set the global gDragging to false.

Now you’ve got a fast, efficient, CPU-friendly set of handlers that won’t bog down the OS or hog system resources. Applications running in the background will still get their fair share of CPU cycles with no performance hit. Your stack will respond much faster and will allow other user actions and scripts to be handled simultaneously. There’s no down side, there’s lots to gain, and your stack will run like a pro.

LiveCode, the easiest, fastest way to program on any OS. A high-level language accompanied by a powerful IDE makes LiveCode a driving force behind modern software development. LiveCode uses a superset of HyperTalk and provides powerful features for serious developers.

LiveCode Journal is a LiveCode journal, full of news, information, member participation, tutorials, and lots of other information. Recommended.

To join the LiveCode Mailing List: Registration Form.

LiveCode Tutorials by Devin Asay at Brigham Young University. A must-read for new LiveCode developers.

To read the LiveCode user forums: https://forums.LiveCode.com/.

Sons of Thunder provides tips, stacks, and useful script snippets for common LiveCode development issues.