New LiveCode User Guide: version 2016 8.1

LiveCode 8.1.0 User Guide 9/12/16

LiveCode 8.1.0 User Guide Overview Known issues Platform support Windows Linux Mac iOS Android HTML5 Setup Installation Uninstallation Reporting installer issues Activating LiveCode Indy or Business edition Command-line installation Command-line uninstallation Command-line activation for LiveCode Indy or Business edition Engine changes Change in empty is among the items of 1,2,3, behavior (8.1.0-rc-2) Filtering array keys and elements has been added to the filter command (8.1.0-rc-1) minStackFileVersion property (8.1.0-rc-1) A new scriptStatus of object property has been implemented (8.1.0-rc-1) Ensure non-BMP characters roundtrip through htmlText (8.1.0-rc-1) Group command does not return new group id in it (8.1.0-rc-1) List folders other than the default folder (8.1.0-dp-3) Fix truncation when saving field paragraphs where length exceeds 32767 characters. (8.1.0-dp-3) Changes to the dontUseQT property of a player object (Windows and OSX) (8.1.0-dp2) Add several IDE messages (8.1.0-dp-2) Improved return command (8.1.0-dp-2) Revert a target stack (8.1.0-dp-2) New vectorDotProduct function (8.1.0-dp-2) Add functions for getting synchronous modifier key state (8.1.0-dp-2) Curly brace subscripts are now a syntax error (8.1.0-dp-2) Improve Android timestamp accuracy for GPS and sensors (8.1.0-dp-2) Improved GPS support on Android and iOS (8.1.0-dp-2) Automatic LCB extension inclusion in standalones (8.1.0-dp-1) Standalone 'Search for inclusions' for mobile deployment (8.1.0-dp-1) Standalone script library inclusions for mobile deployment (8.1.0-dp-1) Windows DirectShow Player Control (8.1.0-dp-1) Property Changes Supported File Formats 1


Add support for custom entitlements for iOS (8.1.0-dp-1) Specific engine bug fixes (8.1.0) Specific engine bug fixes (8.1.0-rc-2) Specific engine bug fixes (8.1.0-rc-1) Specific engine bug fixes (8.1.0-dp-3) Specific engine bug fixes (8.1.0-dp-2) Specific engine bug fixes (8.1.0-dp-1) IDE changes Script compilation errors are now indicated on the project browser (8.1.0-rc-1) Tutorial stack browser display (8.1.0-rc-1) Search for user tutorials (8.1.0-rc-1) Keyboard navigation has been added to the project browser (8.1.0-rc-1) ideControlMoved message (8.1.0-dp-3) Ignore moveStack and resizeStack execution errors in script debug mode (8.1.0-dp3) Deprecated syntax in the dictionary (8.1.0-dp-2) Dictionary UI Improvements (8.1.0-dp-2) Autofocus on message box when typing (8.1.0-dp-2) Standalone Inclusions Interface (8.1.0-dp-1) Specific IDE bug fixes (8.1.0-rc-2) Specific IDE bug fixes (8.1.0-rc-1) Specific IDE bug fixes (8.1.0-dp-3) Specific IDE bug fixes (8.1.0-dp-2) Specific IDE bug fixes (8.1.0-dp-1) LiveCode Builder changes LiveCode Builder Standard Library List operations LiveCode Builder Language Core types Variables Bytecode Blocks Unsafe Attributes Specific Specific Specific Specific

LCB LCB LCB LCB

bug fixes bug fixes bug fixes bug fixes

(8.1.0-rc-1) (8.1.0-dp-3) (8.1.0-dp-2) (8.1.0-dp-1)

LiveCode extension changes Line Graph widget Show and hide the graph lines Marker styles SVG Icon widget

2


Properties Specific extension bug fixes (8.1.0-dp-3) Dictionary additions Previous release notes LiveCode Script Introduction Welcome Where to Begin System Requirements All Operating Systems Requirements for Windows Systems Requirements for Linux Systems Requirements for Mac OS X Systems Using the Documentation Documentation Conventions Menu Reference Keyboard Shortcuts Screen Snapshots Navigating the Documentation Start Center Social Media Links Recent Stacks Quick Links Dictionary LiveCode APIs LiveCode User Guides RevOnline Additional Resources Developer Community Technical Support Getting Started Prerequisites Event Driven Programming Object-Based Programming The ‘Edit’ and ‘Run’ Mode Structuring your Application Cards, Stacks & Files 3


The Structure of a Stack File Opening a Stack File Main Stacks and Substacks Stacks, Stack Files, and Memory Media & Resources How to Use External Files When to use a Database LiveCode Memory Limits A note about entries designated as "Unlimited": Building a User Interface Creating and Organizing Objects Creating Controls with the Tools Palette Alignment & Layering The Keyboard Focus Object & Control Types Stacks – for displaying windows, palettes and dialog boxes Window Types and the Mode of a Stack The Standard Window Types Editable Windows – for documents Modeless Dialog Boxes – for alerts and settings Modal Dialog Boxes – for alerts and settings Palettes – for accessory and tool windows Ask Question Dialog – for asking a question Answer Alert Dialog – for displaying a dialog File Selector Dialogs Color Chooser Dialog Printer Dialogs Alpha Blend Windows – for Enhanced Tooltips and Multimedia System Palettes – for utilities floating above applications Sheet dialog boxes – Mac OS X only Drawers – Mac OS X only Stack menus – for displaying non-standard menus Stack Decorations – for Window Appearance Button Controls – for performing actions Text Field Controls – for displaying or entering text List and Table Field Controls Table Field Control – for displaying a table Data Grid Control – for presenting data Cards Groups & Backgrounds – for organizing, and sharing controls Graphics, Images, Players, Audio & Video Clip Objects – for multimedia Menu Controls – for displaying choices Other Controls Using the Menu Builder Using the Geometry Manager 4


Using Property Profiles 10 Tips for Good User Interface Design Coding in LiveCode The Structure of a Script What is a Script The Types of Handler Message Handlers Function Handlers GetProp Handlers SetProp Handlers Comments Compiling a Script Summary Events What Causes Messages to be Sent Responding to Events The Message Path The Object Hierarchy The Message Path The Message Target Handlers with the Same Name Trapping Messages Blocking System Messages Passing a Message to the Next Object Selectively Trapping or Passing Messages Groups, Backgrounds & The Message Path Commands and Functions Using Built-in Commands and functions Commands Functions Writing function calls with the "the" form Custom Commands and Functions Using custom commands Using custom functions Passing Parameters Passing Multiple Parameters Parameter Variables Parameter variable names Empty parameters Setting a default value for a parameter

5


Implicit Parameters Passing Parameters by Reference Empty parameters Returning Values Returning an Error from a Message Handler Summary Variables Variable Scope Local Variables Script Local Variables Global Variables Variable Names Special Variable Types Parameter variables Environment variables Command-line argument variables The special variable "it" Array Variables Deleting Elements of an Array Listing the Elements in an Array Listing Nested Elements within an Element Transforming a List of Data into an Array Combining the Elements of an Array into a List Nesting an Array More Information Constants Built-in constants User-defined constants Containers, Operators & Sources of Value What is a Container? Setting and Retrieving Data from Containers What are Sources of Value? Getting and Setting Properties What are Literal Strings? Using Literal Strings Quoting strings What are Operators? Numeric Operators String operators

6


Logical Operators Binary versus Unary Operators Conversion of Values Operator Precedence Using the Grouping Operator () Factors and Expressions Defining Factors When it matters Making Decisions If … then … else Switch Extending the Message Path Creating a Code Library Using backScripts Using frontScripts Using a Stack's Script with start using Sending Messages Directly to Objects The send Command versus the call Command Writing reusable code using behaviors Timer Based Messaging Delivering a Message in the Future Repeating a Timer Message Canceling a Timer Message Displaying a List of Pending Timer Messages Tips for Writing Good Code Variable naming Variable scope Use of comments Use of functions Explicit Variables Programming a User Interface Introduction Referring to Objects Referring to objects by name Referring to objects by number Referring to objects by ID Referring to objects by ordinal The special descriptor ‘this’ Control references Nested Object References Properties 7


Using Object Properties Referring to properties Changing properties Property Inheritance Overriding inheritance Global Properties Referring to global properties Changing global properties Saving and restoring global properties Text Related Properties Text style properties Formatted text properties Creating and Deleting Objects The Create Object Command The Delete Object Command Creating Objects Off-screen Using Template Objects Property Arrays using the Properties Property Custom Properties Using Custom Properties Creating a Custom Property The Content of a Custom Property Custom Property Names Referring to Custom Properties Nonexistent Custom Properties Finding out Whether a Custom Property Exists Custom Properties & Converting Text Between Platforms Storing a file in a custom property Deleting a custom property Custom Property Sets Creating custom property sets Custom property set names Referring to custom property sets Finding out whether a custom property set exists The default custom property set Using multiple custom property sets Copying custom properties between property sets Arrays, custom properties, and custom property sets Deleting a custom property set Attaching Handlers to Custom Properties Responding to changing a custom property The structure of a setProp handler Responding to a request for the value of a custom property 8


Virtual Properties When to use virtual properties Handlers for a virtual property Creating new object properties Property Profiles Profile names The master profile Switching between profiles Creating a profile in a handler Adding profile settings in a handler Managing Windows, Palettes and Dialogs Moving a window Changing a window's layer The active window Creating a backdrop Open, Closed, and Hidden Windows The states of a stack Window Types and the Mode Property Window Appearance The Decorations Property Making a stack resizable Irregularly-Shaped and Translucent Windows Programming Menus & Menu Bars Menu Types Button Menus Creating Cascading Menus Ticks, Dashes & Checks in Menus Menu Bars on Linux and Windows Systems Menu Bars on Mac OS X Systems Stack Menus Displaying Context Sensitive Menus Searching and Navigating Cards using the Find Command Using Drag and Drop Initiating a Drag Drop Tracking During a Drag Drop Operation Responding to a Drag and Drop Prevent Dragging and Dropping to a Field Error Handling & Debugging Introduction Common Techniques for Solving Problems Errors During Execution 9


Errors During Compiling Suppressing Errors and Messages Outputting information as your script executes Interrupting Execution The Debugger Custom Error handling The Message Watcher Tracking Down Problems in Standalone Applications LiveCode Data Grid Introduction What is the Data Grid? A Data Grid Table A Data Grid Form Can You Show Me Some Examples? Data Grid Table Data Grid Forms How Do I Create My First Data Grid Table? Locate Data Grid on Tools Palette Drag Data Grid Onto Card Populate Data Grid Using The Property Inspector Customizing Columns Populate Data Grid Using dgText Property Populating the Data Grid Using dgData Property How Do I Create My First Data Grid Form? Locate Data Grid on Tools Palette Drag Data Grid Onto Card Change Style to "Form" Add Some Text Result Example: Creating a List of People Attached Files What You Will Create Add Data Grid to Card Change Data Grid Style The Data That Is Going to Be Displayed in Each Row Edit the Row Template Edit the Row Template Group Rename Label Field Make Name Field Bold Add Title Field Change Text Alignment 10


Add an Image and Resize the Background Graphic Stop Editing the Row Template Group Edit the Row Behavior The FillInData Message The LayoutControl Message Set the Data of the Control The Result Troubleshooting: Row Height Data Grid Fundamentals What Is This "Data Grid Templates" Stack That Appeared in My Project? Data Grid Templates Stack Data Grid Templates Card Contents Opening the Data Grid Templates Stack What Is a Row Template? Row Template How a Record Template Is Used What Is a Column Template? How a Column Template Is Used How Do I Populate a Data Grid With Data? Use The Property Inspector Set the dgText Property Set the dgData Property How Do I Customize a Form's Row Template? Reveal the Row Template Example of a Customized Template Edit Behavior Edit the Behavior Script An Example of a Customized Behavior How Do I Customize a Table's Columns? Use Property Inspector to Create a Column Template Edit the Row Template Group Edit Column Group A Column Template Supporting Controls Behavior Example Result Working With Data Grids (Forms & Tables) How Do I Determine the Selected Line? The dgHilitedLines Property 11


Determining the Line in a Row's Behavior How Do I Get Data Associated With a Row or Column? Getting Data Getting Data Getting Data Getting Data

Associated With the Selected Row When the Selection Changes in a Row Behavior in a Column Behavior

How Do I Add a Row of Data to an Existing Data Grid? Using AddData Using AddLine Scrolling Data Into View and Getting the Data Control How Do I Update Data in a Row? Updating a Row's Data and Refresh Data Grid Automatically Updating a Row's Data Without Refreshing the Data Grid How Do I Clear Data From a Data Grid? How Do I Add a mouseDown Event to the Data Grid Without Breaking It? What Doesn't Work What Does Work: dgMouseDown How Can I Store an Option Menu Value When the User Makes a Selection? Example Data Grid Edit Column Behavior FillInData menuPick The Behavior in Action How Do I Refresh a Data Grid After Making Changes to a Template Through Script? How Do I Use a Template in Multiple Data Grids? Create First Data Grid Create Other Data Grids Result How Can I See What the Data Grid's Internal Array Currently Looks Like? Using PrintKeys How Do I Get Aggregate Values for Columns? Add a getProp to Your Data Grid Script Using the Custom Property The Result How Do I Determine if the Data Grid Has Focus? How Do I Export Data From a Data Grid?

12


The Example Data Grid The Handler for Populating Data Grid Export Handler Example Output How Do I Work With Checkboxes in a Data Grid? Adding a Checkbox to a Form Edit Row Template Group Add a Checkbox Edit Checkbox Properties Delete the Label Field Edit Row Behavior Edit the FillInData Handler Update LayoutControl and ResetData Update Data Grid Row Value When User Changes Checkbox State Populate the Data Grid Test Checking/Unchecking All Checkboxes in a Data Grid Test Working With Data Grid Tables How Do I Change Column Alignment? Using the Property Inspector Using Script How Do I Sort by a Column? Using the Property Inspector Using Script How Do I Resize Columns? Using the Property Inspector Using Script How Do I Override the Default Behavior for Rendering Data to a Cell? Begin With a Data Grid Table Create a Button Set the Script of the Button Customize Behavior Set 'Default Column Behavior' Property Example: Truncate Tail Refresh Example: Coloring Cells Result How Do I Determine if a User Clicks in the Table Header? The Table Header Example 13


How Do I Display a Contextual Menu When the User Clicks on a Column Header? Overview The Code The Result What if I Need to Work With htmlText or rtfText? Option 1: Set the dgProp["Default Column Behavior"] Property Option 2: Create a Custom Column Template How Do I Display Line Numbers in a Table? The Table Add Line Number Column Reorder and Create Column Template Edit Line Number Group Edit Column Behavior Edit Behavior Script Refresh Data Grid The Result But How Do I Set the dgText Then? How Do I Customize Column Sorting? A Data Grid Table The Data Grid Group Script The Result Custom Sort Example How Do I Disable Column Sorting? Sort By No Column Edit Data Grid Script Add SortDataGridColumn Handler How Do I Perform an Action After the User Sorts a Data Grid? Add SortDataGridColumn To Data Grid Group Script How Do I Align Decimals in a Column? Create a Data Grid Table Add Some Data Create Column Template Edit Column Template Edit Column Template Group Create 3 Fields Edit Column Behavior Update FillInData Update LayoutControl Update EditValue Refresh Data Grid 14


Test How Can I Colorize Individual Lines in a Table? Attached Files Coloring a Single Line The Default Custom Column Behavior Working With Data Grid Forms How Do I Create a Form With Variable Line Heights? Turn Off "Empty row height" Edit Row Template Turn Off dontWrap Property Edit Row Behavior Script Field to Resize to Fit Height Refresh Data Grid Contents How Do I Sort Records by a Specific Key's Values? Example Option Menu Code The Result How Do I Create Rows That Can Expand/Contract? Attached Files Expanding and Contracting Rows Setting the Data Grid Properties Updating the Row Behavior Script How Can I Speed Up Drawing When "Fixed Row Height" Is False? CalculateFormattedHeight Using the Built-in Field Editor How Do I Open a Table Cell for Editing? What You Need to Know EditFieldText EditValue EditCell and EditCellOfIndex CloseFieldEditor How Can the User Edit Field Content in a Data Grid Form? What You Need to Know EditFieldText EditValue EditKey and EditKeyOfIndex CloseFieldEditor How Can I Edit the Text as UTF-8, UTF-16 or HTML? 15


The Default Behavior Changing the Default Value For the Editor The Result How Can I Select the Text in the Edit Field When It Opens? The Default Behavior Selecting The Text An Example Script How Do I Save Changes the User Makes in an Editor Field to an External Data Source? When Calling EditFieldText With 3 Parameters (Simpler) When Calling EditFieldText With 1 Parameter (More Flexible) How Can I Customize the Field Editor Behavior? Create Your Behavior Script Customize Your Script Assign Your Custom Behavior to Field Editor Building Standalones With the Data Grid What Do I Need to Do to Deploy a Standalone With a Data Grid? How The Standalone Builder Adds The Necessary Files But What About Launcher Stacks (Splash Stacks)? Useful Things to Know What Sorts of Things Should I Not Do in Order to Avoid Needless Suffering? Don't Call a Handler That Redraws the Data Grid From Within a Control in the Data Grid Don't try to draw a Data Grid on a card that Is not open Do not lock messages when accessing data grid properties. Do not password protect the Data Grid Templates Stack Don't Rename the "Data Grid Templates" Stack Don't Try to Search When Data is Being Loaded From an External Source Stop Editing the Template Group Before Drawing Your Data Grid Advanced Options Displaying Large Amounts of Data Attached Files The dgNumberOfRecords Property GetDataForLine Callback Creating a Data Grid by Hand Copy Data Grid From revDataGridLibrary Set The "style" Property 16


Assign a Row Template How Do I Create a Datagrid Dynamically From Tab Delimited Data Prepare Your Data Create a data grid Create the Row template Fill in Your Data Prepare the Columns of the Data Grid Everything together Data Grid Tips & Tricks How Do I Scroll a Row to the Top of the Data Grid Form? How To Do It The Result How Do I Find Out Which Line the Mouse Is Over? Converting a Database Cursor to a Data Grid Array The Handler How to use Example Printing In LiveCode Introduction Controlling Printer Device Settings Choosing a Printer Choosing Output Mode (e.g. Print to File) Working with Printer Dialogs Saving Printer Settings Paper Related Options Job Related Options Printer Font Metrics (Windows) Printing a Card Card Layout Options Printing Fields & Text Printing a Layout Printing a complex layout Printing Multiple Pages Multiple pages using card printing Multiple pages when using layout printing Working with Scrolling Fields when Layout Printing Working with Print Ranges 17


Printing a Browser Object Processing Text and Data Introduction Using Chunk Expressions Types of Chunks Using Chunks with Containers Using Chunks with Properties The basic chunk types The The The The

Character Chunk Segment Chunk Item Chunk and the itemDelimiter Property Line Chunk and the lineDelimiter Property

Other chunks Specifying a Chunk Negative Indexes in Chunk Expressions Complex Chunk Expressions Using Parentheses in Chunk Expressions Nonexistent Chunks Nonexistent character or segment: Nonexistent item: Nonexistent line: Specifying a Range Counting the Number of segments, Lines or Items Comparing and Searching Checking if a Part is within a Whole Case Sensitivity Checking if text is True, False, a Number, an Integer, a Point, a Rectangle, a Date or a Color Check if a segment, Item or Line Matches Exactly Check if one String Starts or Ends With Another Replacing Text Retrieving the Position of a Matching Chunk Chunks Summary Regular Expressions Searching using a Regular Expression Replacing using a Regular Expression Filtering using a Wildcard Expression International Text Support What are Text Encodings? What are scripts? Introduction to Unicode 18


Creating Unicode Apps Things to look out for Using Arrays When to Use Arrays Array Functions in LiveCode Encoding and Decoding Styled Text URLs Binary Data – Base64 (for MIME Email Attachments and Http Transfers) Binary Data – Arbitrary Types Character to Number conversion Data Compression Encryption Generating a Checksum XML The XML Tree Structure When to use XML Methods for Handling XML in LiveCode The XML Library: Loading, Displaying and Unloading XML The XML Library: Editing XML Sorting The Sort Container Command: Overview The Sort Container Command: Using Sort Keys The Sort Container Command: Sorting Randomly The Sort Container Command: Stable Sorts – Sorting on Multiple Keys Sorting Cards Transferring Information with Files, the Internet and Sockets Introduction File Name Specifications and File Paths What is a File Path? Locating a file The structure of a file path File paths on Windows systems File paths on OS X systems Folder paths File paths for OS X bundles Moving, renaming, or deleting a bundle Referring to files inside a bundle The / character in a file or folder name Absolute and Relative File Paths

19


Absolute file paths Relative file paths Finding the current folder Going up to the parent folder Going up multiple levels Starting at the home directory When to use relative and absolute file paths Special Folders File Types, Application Signatures & File Ownership Windows File Extensions and Ownership Applications that don't own files Applications that own their own files Installing custom icons Custom application icons Custom file icons File extensions OS X File Types and Creators Applications that don't own files Applications that own their own files Creating Files File extensions Mac OS X Classic File Types and Creators Applications that don't own files Applications that own their own files Installing custom icons Custom application icons Linux File Extensions Working with URLs An Overview of URLs URL Schemes The http scheme The ftp scheme Directories on an FTP server The file scheme File path syntax and the file scheme: Conversion of end-of-line markers The binfile scheme The resfile scheme Creating a resource fork 20


Manipulating URL contents

The URL keyword Using the content of a URL Putting data into a URL Chunk expressions and URLs Putting data into a chunk URLs and memory Deleting URLs Uploading and Downloading Files Uploading using the put command Downloading using a URL Non-blocking transfers Using the load command Checking status when using the load command Canceling a file transfer & emptying the cache Uploading and downloading large files using FTP Using callback messages Uploading, downloading, and memory Using a stack on a server Using a compressed stack Saving stacks from a server Other Internet Commands Launching the User's Browser with a URL Working with Web Forms Working with FTP HTTP methods and http URLs HTTP headers Additional Transmission Settings Troubleshooting revBrowser – Rendering a Web Page within a Stack SSL and Encryption Encrypting and Decrypting Data Connecting using HTTPS Implementing your own secure protocols Writing your own protocol with sockets Opening a connection Looking up a host name or IP address 21


Reading and writing data Disconnecting Listening for and accepting incoming connections Handling errors Working With Databases Introduction Introduction to Database Access SQL Databases The Basics of Database Structure SQL and Record Sets – Database Cursors Choosing a Database Reasons to Choose a Database Type Overview of ODBC Performance for Direct Access Versus ODBC Access Software for Database Access Finding Database Drivers MySQL PostgreSQL SQLite ODBC managers and database drivers Working with Media Introduction Bitmap Images Importing Images Importing Referenced Images Import using Screen Capture Creating Images Using the Paint Tools Scripting with the Paint Tools Manipulating Binary Image Data Rendering an Image from Objects Exporting Images Copying and Pasting Images Working with Animated GIFs Working with Vector Graphics The Vector Graphic Tools Creating Graphics by Script Manipulating graphics by script Working with Video The Player Object 22


Working with Sounds Importing an Audio Clip Playing an Audio Clip Working with Visual Transition Effects Creating Custom Skins Custom Themed Buttons Irregular Windows Blend Modes (transfer modes or inks) Full screen mode Displaying a Backdrop The LiveCode IDE Introduction The Menu Bar The The The The The The The The The

File Menu Edit Menu Tools Menu Object Menu Text Menu Development Menu View Menu Window menu Help Menu

The Property Inspector Property Inspector settings The Script Editor Main Script Area Breakpoints Area Apply Button Errors Pane Handler List Documentation Pane Search Results Pane Script Tabs The Debugger Continue Stop Debugging Show Next Statement Step Into Next Statement Step Over Next Statement Step Out Debug Context Variable Watcher 23


Breakpoint Management The Script Editor Menubar The The The The The

File Menu Edit Menu Debug Menu Handler Menu Window Menu

The Message Box Message Box settings Single and Multiple Line Modes Global Properties Global Variables Pending Messages Front Scripts & Back Scripts Stacks In Use The Toolbar Find and Replace Keyboard Shortcuts Deploying Your Application Introduction Building a Standalone Application Standalone Applications Settings HTML5 Deployment Introduction Supported browsers HTML5 engine features How to deploy an app to HTML5 Step by step Contents of the HTML5 standalone Testing your HTML5 app with a local web server Reporting bugs Advanced: HTML5 standalone filesystem Advanced: Embedding an HTML5 standalone in a web page The canvas The Module object Engine download Bringing it all together Advanced: Speeding up engine download Advanced: Customizing the Module object

24


Mac Deployment Introduction 64-bit engine features The IDE How to deploy a 64-bit Mac standalone Building Testing Reporting bugs Extending LiveCode Introduction LiveCode Builder Extensions Creating LiveCode Builder Extensions Extension Builder Create your Own Simple Widget Create a .lcb file Declare Type and Identifier Declare Meta Data Importing libraries Core Handlers Draw a Pink Circle Test the Code Properties Loading and Saving widget data Understanding Error Messages LiveCode Builder API Creating Libraries Loading and Creating Widgets Manually Composed Widgets A simple composed widget Documenting Your Extension Adding API Markup Adding a User Guide Packaging Extensions Package requirements Other ways to extend the Built-in Capabilities Communicating with other process and applications Reading and writing to the command shell Launching other applications Closing another application 25


Communicating with other processes Using AppleScript and VBScript (Open Scripting Architecture or Windows Scripting Host) AppleEvents Using Local sockets Externals – code written in lower level languages The Externals SDK LiveCode Builder Bytecode Reference Introduction Operations Jump Jump If False Jump If True Assign Constant Assign Return Invoke Invoke Indirect Fetch Store Assign List Assign Array Reset LiveCode Builder Language Reference Introduction Tokens Comments Line continuation Case-Sensitivity Typing Modules Metadata Imports Definitions Constants Types Handler Types Variables Handlers Foreign Handlers Properties Events

26


Statements Variable Statements If Statements Repeat Statements Throw Statements Return Statements Transfer Statements Call Statements Bytecode Statements Unsafe Statements Expressions Constant Value Expressions Variable Expressions Result Expressions List Expressions Array Expressions Call Expressions LiveCode Builder Style Guide Introduction Copyright headers Naming Module name Naming variables and parameters Naming handlers Documenting the source code Named constants Whitespace Indentation Handler declarations, definitions and calls LiveCode Documentation Format Reference Introduction Format Element names Name (required) Synonyms Type (required) Syntax (required for API-level entries) Summary (required) Associated Introduced OS Platforms 27


Example Parameters Value and return parameters Description (required) References Tags Other documentation syntax Separate docs files Inline documentation Separate docs files examples Dictionary example Library example Inline examples LiveCode Builder syntax example LiveCode Builder handler example LiveCode script handler example

LiveCode 8.1.0 Release Notes

28


Overview LiveCode 8.1 provides important improvements for delivering high-quality cross-platform applications! LiveCode Indy and Business editions now come with the tsNet external, which supercharges LiveCode's Internet features and performance. LiveCode 8.1 also introduces mergHealthKit, for accessing activity, sport and health data on iOS devices. The standalone builder now has a greatly-improved user experience for including externals, script libraries and LiveCode Builder extensions in your cross-platform application. Usually, it'll now do the right thing automatically, but you can still select the specific inclusions you need. The IDE has lots of other upgrades, too: a keyboard-navigable Project Browser that highlights any scripts that failed to compile, an improved dictionary user interface, and access to the message box just by starting to type. The player control can be used in Windows application without any need for users to install any additional libraries or dependencies, thanks to a brand new player implementation based on DirectShow. For most apps, it should now be unnecessary to install or use QuickTime at all. The LiveCode Builder programming language has had some enhancements as part of the Infinite LiveCode project. Variables now get initialised by default, unsafe blocks and handlers can be used to flag sections of code that do dangerous things, and you can even include raw bytecode if necessary.

29


Known issues The installer will currently fail if you run it from a network share on Windows. Please copy the installer to a local disk before launching on this platform. The browser widget does not work on 32-bit Linux. 64-bit standalones for Mac OS X do not have support for audio recording or the revVideoGrabber external.

30


Platform support The engine supports a variety of operating systems and versions. This section describes the platforms that we ensure the engine runs on without issue (although in some cases with reduced functionality).

Windows LiveCode supports the following versions of Windows: Windows Windows Windows Windows Windows Windows Windows

XP SP2 and above Server 2003 Vista SP1 and above (both 32-bit and 64-bit) 7 (both 32-bit and 64-bit) Server 2008 8.x (Desktop) 10

Note: On 64-bit Windows installations, LiveCode runs as a 32-bit application through the WoW layer.

Linux LiveCode supports the following Linux distributions, on 32-bit or 64-bit Intel/AMD or compatible processors: Ubuntu 14.04 and 16.04 Fedora 23 & 24 Debian 7 (Wheezy) and 8 (Jessie) [server] CentOS 7 [server] LiveCode may also run on Linux installations which meet the following requirements: Required dependencies for core functionality: glibc 2.13 or later GLib 2.0 or later Optional requirements for GUI functionality: GTK/GDK 2.24 or later Pango with Xft support esd (optional, needed for audio output) mplayer (optional, needed for media player functionality) lcms (optional, required for color profile support in images) gksu (optional, required for privilege elevation support) Note: If the optional requirements are not present then LiveCode will still run but the specified features will be disabled. Note: The requirements for GUI functionality are also required by Firefox and Chrome, so if your 31


Linux distribution runs one of those, it will run LiveCode. Note: It may be possible to compile and run LiveCode Community for Linux on other architectures but this is not officially supported.

Mac The Mac engine supports: 10.6.x (Snow Leopard) on Intel 10.7.x (Lion) on Intel 10.8.x (Mountain Lion) on Intel 10.9.x (Mavericks) on Intel 10.10.x (Yosemite) on Intel 10.11.x (El Capitan) on Intel

iOS iOS deployment is possible when running LiveCode IDE on a Mac, and provided Xcode is installed and has been set in LiveCode Preferences (in the Mobile Support pane). Currently, the supported versions of Xcode are: Xcode Xcode Xcode Xcode Xcode

4.6 on MacOS X 10.7 5.1 on MacOS X 10.8 6.2 on MacOS X 10.9 6.2 and 7.2 on Mac OS X 10.10 7.3 on MacOS X 10.11

It is also possible to set other versions of Xcode, to allow testing on a wider range of iOS simulators. For instance, on Yosemite, you can add Xcode 5.1 in the Mobile Support preferences, to let you test your stack on the iOS Simulator 7.1. We currently support the following iOS Simulators: 6.1 7.1 8.2 9.2 9.3

Android LiveCode allows you to save your stack as an Android application, and also to deploy it on an Android device or simulator from the IDE. Android deployment is possible from Windows, Linux and Mac OSX. The Android engine supports devices using ARMv6, ARMv7 or ARMv8 processors. It will run on the following versions of Android:

32


2.3.3-2.3.7 (Gingerbread) 4.0 (Ice Cream Sandwich) 4.1-4.3 (Jelly Bean) 4.4 (KitKat) 5.0-5.1 (Lollipop) 6.0 (Marshmallow) To enable deployment to Android devices, you need to download the Android SDK, and then use the 'Android SDK Manager' to install: the latest "Android SDK Tools" the latest "Android SDK Platform Tools" You also need to install the Java Development Kit (JDK). On Linux, this usually packaged as "openjdk". LiveCode requires JDK version 1.6 or later. Once you have set the path of your Android SDK in the "Mobile Support" section of the LiveCode IDE's preferences, you can deploy your stack to Android devices. Some users have reported successful Android Watch deployment, but it is not officially supported.

HTML5 LiveCode applications can be deployed to run in a web browser, by running the LiveCode engine in JavaScript and using modern HTML5 JavaScript APIs. HTML5 deployment does not require any additional development tools to be installed. LiveCode HTML5 standalone applications are currently supported for running in recent versions of Mozilla Firefox, Google Chrome or Safari. For more information, please see the "HTML5 Deployment" guide in the LiveCode IDE.

33


Setup Installation Each version of LiveCode installs can be installed to its own, separate folder. This allow multiple versions of LiveCode to be installed side-by-side. On Windows (and Linux), each version of LiveCode has its own Start Menu (or application menu) entry. On Mac OS X, each version has its own app bundle. On Mac OS X, install LiveCode by mounting the .dmg file and dragging the app bundle to the Applications folder (or any other suitable location). For Windows and Linux, the default installation locations when installing for "All Users" are: Platform

Path

Windows

/RunRev/LiveCode

Linux

/opt/livecode/livecode-

The installations when installing for "This User" are: Platform

Path

Windows

/RunRev/Components/LiveCode

Linux

~/.runrev/components/livecode-

Note: If installing for "All Users" on Linux, either the gksu tool must be available, or you must manually run the LiveCode installer executable as root (e.g. using sudo or su).

Uninstallation On Windows, the installer hooks into the standard Windows uninstall mechanism. This is accessible from the "Add or Remove Programs" applet in the windows Control Panel. On Mac OS X, drag the app bundle to the Trash. On Linux, LiveCode can be removed using the setup.x86 or setup.x86_64 program located in LiveCode's installation directory.

Reporting installer issues If you find that the installer fails to work for you then please report it using the LiveCode Quality Control Centre or by emailing [email protected]. Please include the following information in your report: Your platform and operating system version The location of your home or user folder The type of user account you are using (guest, restricted, admin etc.) 34


The installer log file. The installer log file can be located as follows: Platform

Path

Windows 2000/XP

//Local Settings/

Windows Vista/7

//AppData/Local/RunRev/Logs

Linux

/.runrev/logs

Activating LiveCode Indy or Business edition The licensing system ties your product licenses to a customer account system, meaning that you no longer have to worry about finding a license key after installing a new copy of LiveCode. Instead, you simply have to enter your email address and password that has been registered with our customer account system and your license key will be retrieved automatically. Alternatively it is possible to activate the product via the use of a specially encrypted license file. These will be available for download from the customer center after logging into your account. This method will allow the product to be installed on machines that do not have access to the internet.

Command-line installation It is possible to invoke the installer from the command-line on Linux and Windows. When doing command-line installation, no GUI will be displayed. The installation process is controlled by arguments passed to the installer. Run the installer using a command in the form:

install noui [OPTION ...]

where should be replaced with the path of the installer executable or app (inside the DMG) that has been downloaded. The result of the installation operation will be written to the console. The installer understands any of the following OPTION s: Option

Description

-allusers

Install the IDE for "All Users". If not specified, LiveCode will be installed for the current user only.

desktopshortcut

Place a shortcut on the Desktop (Windows-only)

-startmenu

Place shortcuts in the Start Menu (Windows-only)

-location LOCATION

The folder to install into. If not specified, the LOCATION defaults to those

-log LOGFILE

described in the "Installation" section above. The file to which to log installation actions. If not specified, no log is generated. 35


Note: the command-line installer does not do any authentication. When installing for "All Users", you will need to run the installer command as an administrator. As the installer is actually a GUI application, it needs to be run slightly differently from other command-line programs. On Windows, the command is:

start /wait install noui [OPTION ...]

Command-line uninstallation It is possible to uninstall LiveCode from the command-line on Windows and Linux. When doing command-line uninstallation, no GUI will be displayed. Run the uninstaller using a command of the form:

uninstall noui

Where is .setup.exe on Windows, and .setup.x86 on Linux. This executable, for both of the platforms, is located in the folder where LiveCode is installed. The result of the uninstallation operation will be written to the console. Note: the command-line uninstaller does not do any authentication. When removing a version of LiveCode installed for "All Users", you will need to run the uninstaller command as an administrator.

Command-line activation for LiveCode Indy or Business edition It is possible to activate an installation of LiveCode for all users by using the command-line. When performing command-line activation, no GUI is displayed. Activation is controlled by passing command-line arguments to LiveCode. Activate LiveCode using a command of the form:

activate -file LICENSEFILE -passphrase SECRET

where should be replaced with the path to the LiveCode executable or app that has been previously installed. This loads license information from the manual activation file LICENSEFILE , decrypts it using the given SECRET passphrase, and installs a license file for all users of the computer. Manual activation files can be downloaded from the My Products page in the LiveCode account management site.

36


It is also possible to deactivate LiveCode with:

deactivate

Since LiveCode is actually a GUI application, it needs to be run slightly differently from other command-line programs. On Windows, the command is:

start /wait activate -file LICENSE -passphrase SECRET start /wait deactivate

On Mac OS X, you need to do:

/Contents/MacOS/LiveCode activate -file LICENSE -passphrase SECRET /Contents/MacOS/LiveCode deactivate

37


Engine changes Change in empty is among the items of 1,2,3, behavior (8.1.0-rc-2) In previous versions of LiveCode is among the items of behaved incorrectly when a trailing delimiter was present. Trailing delimiters are generally ignored in the LiveCode engine and legacy behaviors where they are not are documented anomalies that are maintained for backwards compatibility reasons. This change resolves the anomaly detailed in bug report 16297 For example:

put the number of items of "1,2,3," is 3 --> puts true in all engines put empty is among the items of "1,2,3," --> puts true in LiveCode 6 put empty is among the items of "1,2,3," --> puts false in LiveCode 8

Warning If your stacks depend on the legacy anomalous behavior they should be checked to ensure all trailing empty items are wrapped by an item delimiter

Filtering array keys and elements has been added to the filter command (8.1.0-rc-1) The filter command now supports the filtering of arrays by matching keys or elements. Example:

local tArray put true into tArray["foo"] put false into tArray["bar"] filter keys of tArray with "f*" put the keys of tArray is "foo"

minStackFileVersion property (8.1.0-rc-1) A new stack property has been added to determine the minimum stack file version that can be safely used to save a stack without data loss. For example, if a widget is on the stack the minStackFileVersion will be 8.0 and saving with a lower stack file version will result in the loss of the widget from the stack. The minimum minStackFileVersion reported by the property is 7.0.

A new scriptStatus of object property has been implemented (8.1.0-rc-1) 38


Use the scriptStatus of

New LiveCode User Guide: version 2016 8.1

Recommend Documents