4.6 Features Overview
A look at what you can expect from our latest LiveCode release.

by Hanson Schmidt-Cornelius

Many of you have been waiting eagerly for our 4.6 release, and now, here it is! This latest release is packed to the brim with goodies. Our focus has been on expanding our mobile capability. Over 20 new iOS feautures means that iOS is now a solid and maturing feature of the LiveCode product. At the same time we have improved and added to our desktop platforms with over a dozen new features and ehancements.

In this article I will discuss some of the features we have been working on and introduce you to a selection of them with scaled down examples. You can read all about these examples in more detail in the lessons section of our website.

On the Desktop

Desktops are our longest standing supported platforms. Their feature set was already comprehensive; and progress in 4.6 builds on that, with 13 new features as well as numerous bug fixes and other improvements. In particular, we improved and added the following features:

• The import and export snapshot commands have been updated with the ability to specify whether graphic effects and the blendLevel should be applied to objects before they are rendered.
• Large Image support on OS X
• PDF printing, using the print link command has been updated to include a link value that provides additional document cross referencing features.
• PDF printing, using the print bookmark command has been updated to provide features for document outline support.
• Several field properties were added and updated in the field object that are related to plain text export.
• Better support for manipulating Preferences and About menu items on Mac
• SQLite upgraded to 3.7.2 with Full Text Search capability
• A feature was added to configure a group to turn off automatic clamping of scroll offsets when scrollbars are not present.
• The function randomBytes() was added to generate an arbitrary amount of cryptographic-quality random data.
• SHA-1 was added to compute a 20 binary byte digest of a block of data.
• Commands encrypt and decrypt have been updated to support RSA public key encryption.
• Experimental support for simple lists in fields

Example: Adding External Links and Document Outlines to PDF Files

PDF generation has been available in LiveCode for quite a while, but 4.6 has seen the addition of new PDF generation commands that provide external cross reference support and the ability to create bookmarks. Link generation is available via the command print link, and the document outline can be created by using the print bookmark command. These commands are used in similar ways and detailed information on their use can be found in the LiveCode dictionary that is available in the LiveCode development environment.

To use the print bookmark command you specify the bookmark title, the level and the location. The title is the name of the bookmark that is to be displayed in the outline, the level is the depth of the bookmark and the location is an x, y coordinate describing where on the current page the bookmark is to appear.

The print link command requires the external link and a location in the PDF document that should later present a selectable region that provides access to the link.

The following example places level 1 bookmarks for chapter titles, level 2 bookmarks for a.b sections level 3 bookmarks for a.b.c sections and a rectangle with a link to http://lessons.runrev.com into a PDF document:

# path to the pdf file we want to create
put specialFolderPath("documents") & "/UserGuide.pdf" into \
       tPDFPath

open printing to pdf tPDFPath
if the result is "Cancel" then
   # the user has canceled printing
   exit printCards
else
   print card 1 of this stack into 0,0,575,800
   print bookmark "1 Introduction" with level 1 at 4,2
   print bookmark "1.1 Welcome" with level 2 at 4,96
   print break
   print card 2 of this stack into 0,0,575,800
   # create an external link in the PDF document
   print link to url "http://lessons.runrev.com" with rect \
          408,34,518,52
   # print bookmarks
   print bookmark "1.2 Where to begin" with level 2 at 4,2
   print bookmark "1.3 System Requirements" with level 2 at 4,96
   print bookmark "1.3.1 All Operating Systems" with level 3 at \
          4,273
   print bookmark "1.3.2 Requirements for Windows System" with \
          level 3 at 4,414
   print bookmark "1.3.3 Requirements for Linux Systems" with \
          level 3 at 4,605
end if
close printing

This code would typically be found in a command or function that is called from somewhere in a LiveCode application. The print bookmark commands used in this example are specific to the document that is being generated here. You may prefer to use variables in your code, allowing you to populate the bookmark values in a more generic fashion.

The following figure shows you what a typical PDF document looks like when a document outline has been inserted:

You can read the full release notes for LiveCode 4.6 on the desktop here.

In LiveCode iOS

Support for iOS has only been introduced recently but the feature list is extensive, with this release seeing the addition of a substantial number of new features and enhancements of existing features. With the addition of over 20 new features LiveCode iOS now supports:

• Support was added for the remaining UIWebView properties.
• visual effects in sub-regions of the display was added.
• multichannel sound  (no longer considered experimental).
• revZip, revXML, dbSQlite and custom externals
• configuring the iOS idleTimer was added.
• import and export from rect.
• return the camera information, using iphoneCameraFeatures().
• picking from a specific camera on multi-camera devices.
• the flip visual effect, allowing the background color of the stack to be displayed behind the flipped page.
• list native controls, using iphoneControls().
• creating named native controls.
• clearing pending interactions, using iphoneClearTouches.
• reading system identifiers was added, using: iphoneSystemIdentifier().
• preparing a sound on a channel, but without playing it, .
• pausing and resuming a sound on a channel.
• querying the status of a sound channel was added.
• native player control was added.
• improved email composition.
• Interoperability of play video and native player control on iOS < 4.2
• All iphoneComposeMail arguments  nowoptional.
• pattern fills was implemented.
• native text input control was added.
• network reachability tracking  (experimental)
• playing sections of video (experimental)
• custom fonts in iOS 3.2+.

• LiveCode 4.6 also improves on the following features:

  • The ability to determine the display scale, allowing applications to be written for both retina and non-retina display devices
  • The iPad popup lists have been changed to be dismissed after the selection
  • The screenRect properties were changed to take orientation into account
  • Positioning of the text entry field in the ask dialog was improved for portrait and landscape display.
  • iphonePick was updated to use check mark on iPad.
  • iphonePickPhoto was improved on iPad to make it display relative to the target and allow orientation changes.
  • The inputReturnKey message was added to the native input control.
  • The code-signing identity detection and use was improved.
  • The Exits on Suspend option was removed from the settings pane and forced to always be YES

  You can read the full release notes for LiveCode 4.6 iOS here.

  Example: Sending HTML E-Mails with Attachments

  LiveCode supports revMail to send e-mail via the local e-mail client. This feature is great for sending text based e-mails without attachments. If you want to add more mailing features in iOS, then you need to use either iphoneComposeMail, iphoneComposeUnicodeMail or iphoneComposeHtmlMail. These commands allow you to send emails in plain text, Unicode or HTML and allow you to add attachments.

  The following example shows you how to send an HTML E-Mail with a text attachment from an iOS device, such as an iPhone:
  

  # declare the variables that hold the information that is to be
  # included in the e-mail
  local tBody, tAttachment 
  
  # test if the current device can send e-mails
  if iphoneCanSendMail () is true then 
     # populate the e-mail body
     
     put "This text is <b>bold</b><br>" & return & \
            "This text is <i>emphasized</i><br>" & return & \
            "This text is <small></small><br>" & return & \
            "This text is <del>deleted</del>" & return & \
            "This is a red table" & return & \
            "<table border=" & quote & "1" & quote && "bgcolor=" \
            & quote & "red" & quote & ">" & return & \
            "<tr>" & return & \
            "<td>col 1, row 1</td>" & return & \
            "<td>col 2, row 1</td>" & return & \
            "<td>col 3, row 1</td>" & return & \
            "</tr>" & return & 
     "<tr>" & return & \
            "<td>col 1, row 2</td>" & return & \
            "<td>col 2, row 2</td>" & return & \
            "<td>col 3, row 2</td>" & return & \
            "</tr>" & return & \
            "</table>" into tBody
     
     # populate the e-mail attachment
     
     put ":-)" into tAttachment["data"]
     put "happy.txt" into tAttachment["name"]
     put "text/plain" into tAttachment["type"]
     # send the e-mail
     iphoneComposeHtmlMail "Send this e-mail", "nobody@runrev.com" \
            , "someone@runrev.com", empty, tBody, tAttachment
  else
     answer "Your device cannot be used to send e-mail" with "Okay"
  end if
  

  You will notice that most of the code is in fact the HTML sample message body of the e-mail. The attachment is created in three lines and the command that launches the native e-mail client is only one line of LiveCode. Once you execute the code, either in a button raised event or somewhere else within your LiveCode application, you would be presented with the following iPhone display.

  
  
  

  The HTML appears rendered in the display and the text attachment appears at the bottom left hand side of the screen. All you have to do now is press Send to send the e-mail you created with LiveCode.

  On the Desktop and in iOS

  Some of the features we added to LiveCode apply to our desktop platforms as well as iOS, for example SQLite database support. The last example I will cover here can be run under Windows, on a Mac or on an iPhone.

  Example: Using the SQLite Database

  SQLite database support is provided for both the iOS and desktop platforms. Code can easily be written to work on these supported platforms without the need for modification.

  The example here creates one table that holds contact details from some of the staff here at RunRev.

  Although very short, this example already demonstrates the database potential and power you can add to your cross platform applications, using only a few lines of LiveCode.

  First connect to the database. This can be accomplished by a command such as the following one:

  command databaseConnect
     local tDatabasePath, tDatabaseID 
     
     # the database must be in a writable location
     put specialFolderPath ("documents") & "/runrevemails.sqlite" \
            into tDatabasePath
     
     # open a connection to the database
     # if the database does not already exist it is created
     put revOpenDatabase ("sqlite", tDatabasePath, , , , ) into \
            tDatabaseID
     
     # store the database id as a custom property so other
     # handlers can access it
     put tDatabaseID into sDatabaseID
  end databaseConnect
  

  Then create a table in the database. Here we are creating a contact_details table that holds names and e-mail addresses:

  command databaseCreateTable
     
     # add a contact_details table to the database
     put sDatabaseID into tDatabaseID
     put "CREATE TABLE contact_details \
  (name char(50), email char(50))" into tSQL
     revExecuteSQL tDatabaseID, tSQL
  end databaseCreateTable
  

  Next, add some records into the database. We are adding some details of staff members for a company:

  command databaseInsertContactDetails
     # insert names and email addresses into the database
     put sDatabaseID into tDatabaseID
     put  "INSERT into contact_details VALUES\
   ('Joe Bloggs','joe.bloggs@email.com');" into tSQL
     put "INSERT into contact_details VALUES \
  ('Jane Doe','jane.doe@email.com');" after tSQL
     put  "INSERT into contact_details VALUES\
   ('Tom Smith','tom.smith@email.com')"; after tSQL
     put "INSERT into contact_details VALUES \
  ('Mary Brown','mary.brown@email.com')" after tSQL
     revExecuteSQL tDatabaseID, tSQL
  end databaseInsertContactDetailsrtCon
  

  Finally, retrieve the data that was just added into the database:
  

  function databaseGetContactDetails
     
     # query the database for contact details to be displayed in
     # the field
     put sDatabaseID () into tDatabaseID
     put "SELECT * from contact_details" into tSQL
     put revDataFromQuery (tab, return, tDatabaseID, tSQL) into \
            tRecords
     return tRecords
  end databaseGetContactDetails
  

  These four very short commands and function can be embedded in a LiveCode application that may look something like the following one on a desktop application:

  

  Or something like this one on an iPhone:

  

  I hope you find this short summary and the examples inspirational for your LiveCode endeavors. Remember that there is a lot more information about the new LiveCode features in the product documentation and on our web page at www.runrev.com.

  About the Author Hanson Schmidt-Cornelius is an experienced software developer with an interest in artificial intelligence.