revUp - Updates and news for the LiveCode community
Issue 115 | July 29th 2011 Contact the Editor | How to Contribute

LiveCode Dictionary
In response to popular demand, we have updated the dictionary and are getting it into print for you

by Mark Taoilinn


It might not earn a nomination for the booker prize, but the new LiveCode printed dictionaries are essential reference materials for any serious LiveCode developers. It’s also a great learning tool for any new LiveCode users just starting out. Completely revised and reworked, the two volume dictionary is fully up to date as at LiveCode version 4.6.3 which was launched last week.

During the release of LiveCode 4.6.3 we revised and edited the dictionary, to make sure that you always have a fully up to date reference tool at your disposal. As part of that project we included over 150 new entries, many of them for the mobile and server platforms. All the entries include example of how to use the terms/keywords and provide cross references to similar terms.

Each entry is based on a standard template:

  • Keyword: what the entry is, e.g. launch url
  • Type: What sort of keyword is this: message/command/
  • Syntax: How to use the keyword
  • See also: a cross reference to related terms
  • Introduced: The version of LiveCode that the dictionary entry was first introduced for
  • Platforms: which platforms this works for: mobile/server/desktop
  • Supported operating systems:  e.g. for mobile, is it iOS or Android
  • Summary: a one line summary of the purpose of this term
  • Examples: a sample of how best to use this term
  • Parameters: values associated with the term
  • Comments: Any other useful things you should know about this term

I asked Ben Beaumont, LiveCode Product Manager, what his favourite new dictionary entries are. He immediately answered “iphonecontrolget” - an entry that Ben prepared personally and which took over a day to prepare. (Not as much hard work as Henry Bradley who spent years writing the Oxford English Dictionary’s longest entry: the verb “set” which needed 60,000 words to describe all 430 senses). The “iphonecontrolget” entry is far too long to show you here, so here’s some other examples that we like instead.

Keyword: iphoneExportImageToAlbum

Type: command

Syntax:  __
iphoneExportImageToAlbum imageTextOrControl

See Also: mobilePickPhoto Command, mobileCameraFeatures Function

Introduced: 4.6.1

Platforms: Mobile

Supported Operating Systems: ios

Saves an image to the user's photo album.

iphoneExportImageToAlbum tImageText

iphoneExportImageToAlbum the text of image 1

put the long ID of image "myImage" into tImageID
iphoneExportImageToAlbum tImageID

use the iphoneExportImageToAlbum to save an image to the user's photo album. If the device has a camera, the image is saved to the Camera Roll, other wise it is saved to the Saved Photos album.

imageTextOrControl - One of the following:

  • binary data - The binary data of an image (the 'text') in PNG, GIF or JPEG format.
  • image long id - The long id of an image object containing an image in PNG, GIF or JPEG format.__

The iphoneExportImageToAlbum command returns empty in the result if exporting succeeded. Otherwise it will return one of:
   * 'could not find image' - the image object could not be found
   * 'not an image' - the object was not an image
   * 'not a supported format' - the image object in not of PNG, GIF or JPEG format'
   * 'export failed - an error occurred while trying to save the image to the album

Note: When running in the simulator, there needs to be at least one image in the photo album for exporting to succeed. You can add images to the photo album in a simulator by dragging an image on the simulator window, and saving the image to album from Safari (click and hold on the image to bring up an alert with the option).


Keyword: mobileComposeMail

Type: command

Syntax:  __
mobileComposeMail subject, [recipients, [ccs, [bccs, [body, [attachments]]]]]


See Also: revGoURL Command, revMailUnicode Command, revMail Command, mobileComposeUnicodeMail Command, mobileComposeHtmlMail Command, mobileCanSendMail Function

Introduced: 4.6

Changed: 4.6.1

Platforms: Mobile: iOS & Android

Supported Operating Systems:

Opens a new email message in the user's email program.

mobileComposeMail "Test E-mail", "",,, "This is the e-mail body text", tAttachment

mobileComposeMail "Help", "",,,field "Message"

put "Hello World!" into tAttachment["data"]
put "text/plain" into tAttachment["type"]
put "Greetings.txt" into tAttachment["name"]
mobileComposeMail "Greetings", "",,,, tAttachment

Use the mobileComposeMail command to create a text email message with attachments from within a stack on iOS or Android.

subject - The subject line of the email.
recipients - A comma delimited list of email addresses to be placed in the 'To' field.
ccs - A comma delimited list of email addresses to be placed in the 'CC' field.
bccs - A comma delimited list of email addresses to be placed in the 'BCC' field.
body - The body text of the email.
attachments - Either empty to send no attachments, a single attachment array or a one-based numeric array of attachment arrays to include. The attachments parameter consists of either a single array, or an array of arrays listing the attachments to include. A single attachment array should consist of the following keys:

  • data - The binary data to attach to the email (not needed if a file is present).
  • file - The filename of the file on disk to attach to the email (not needed if data present).__

Upon completion of a compose request, the result is set to one of the following:
* sent - the email was sent successfully
* cancel - the email was not sent, and the user elected not to save it for later

This command interfaces with the iOS and Android mail composition interface.

If you specify a file for the attachment, the engine tries to use the least amount of memory by asking the operating system to only load it from disk when the file is needed. Therefore, using mobileComposeMail should be the preferred method when attaching large amounts of data to an e-mail.
For example, sending multiple attachments may be done like this:

put Hello World! into tAttachments[1][data]
put text/plain into tAttachments[1][type]
put Greetings.txt into tAttachments[1][name]
put Goodbye World! into tAttachments[2][data]
put text/plain into tAttachments[2][type]
put Farewell.txt into tAttachments[2][name]
mobileComposeMail tSubject, tTo, tCCs, tBCCs, tBody, tAttachments

Some devices are not configured with e-mail sending capability. To determine if the current device is, use the mobileCanSendMail function. This returns true if the mail client is configured.

Note: Once the mobileComposeMail command is called, you have no more control over what the user does with the message. They are free to modify the message and the addresses as they see fit.

And lastly:


Type: keyword

See Also: outputTextEncoding Property, $_SERVER Keyword, $_POST Keyword, $_POST_BINARY Keyword, $_POST_RAW Keyword, $_GET_RAW Keyword, $_GET_BINARY Keyword

Introduced: 4.6.3

Platforms: Server

Supported Operating Systems:

$_GET is an array variable, translated from the QUERY_STRING. It assumes the query string is encoded as url-form-encoded data.

put $_GET into tGetArray,

#For example: URL ""
put $_GET["cat"] into tCategory
put $_GET["ISBN"] into tISBN


if $_GET["cat"] is "books" then
  ... do something ...
end if

Use the $_GET keyword to access the array generated from the QUERY_STRING component of a URL.

$_GET is only available when running in CGI mode (Server).

Note: The data is converted to the native character set from the character set defined in the outputTextEncoding.

So that’s our new dictionary. As Heather Nagey, our Customer Services manager said recently, you can keep it by your bed, take it on holiday, read it in the bathroom... the options on endless. The dictionary is available in the store now and will be shipping in 6 - 8 weeks.



About the Author

Mark Taoilinn is Sales and Marketing Manager for RunRev Ltd.


Main Menu

What's New

Marketplace three for two during July