livecode 5.5.1 release notes€¦ · livecode 5.5.1 is an update to 5.5, introducing mobile...

5.5.x Release Notes – Revision 15 – 2012-06-20

LiveCode 5.5.1 Release Notes

Table of ContentsOverview.............................................................................................................................................. 4Known issues........................................................................................................................................4Platform support................................................................................................................................... 4

Windows.......................................................................................................................................... 4Linux................................................................................................................................................4Mac.................................................................................................................................................. 5Proposed changes.............................................................................................................................5

Setup..................................................................................................................................................... 6Installation....................................................................................................................................... 6Uninstallation...................................................................................................................................6Reporting installer issues................................................................................................................. 6Activation.........................................................................................................................................7Multi-user and network install support (4.5.3)................................................................................ 7

Command-line installation.......................................................................................................... 7Command-line activation............................................................................................................ 8

Engine Changes.................................................................................................................................. 10The unicodeToolTip property (5.5 RC1)....................................................................................... 10Paragraph hiding (5.5 DP3)........................................................................................................... 10Updated htmlText (5.5 DP3)..........................................................................................................10Updated rtfText (5.5 DP3 – Updated 5.5 RC1)..............................................................................11Unlinking of text properties in objects (5.5 DP2)..........................................................................11Manipulating Unicode in objects (5.5 DP2).................................................................................. 11New Field Features........................................................................................................................ 12

Flagged char ranges (5.5 DP1)..................................................................................................12Chunk index conversion (5.5 DP1)...........................................................................................13Metadata char property (5.5 DP1).............................................................................................13Individual textStyle manipulation (5.5 DP1)............................................................................ 13textChanged message (5.5 DP1)............................................................................................... 14Unicode-aware field chunks (5.5 DP1).....................................................................................15styledText content format (5.5 DP1 )........................................................................................15Hierarchical list support (5.5 DP1)........................................................................................... 18Paragraph level properties (5.5 DP1)........................................................................................ 18vGrid column visibility and tabWidths (5.5 DP1).................................................................... 19vGrid fixed width table mode (5.5 DP1)...................................................................................20Unicode handling changes (5.5 DP2)....................................................................................... 20Unlinking of text properties in fields (5.5 DP2)....................................................................... 21Explicit line-breaks in fields (5.5 DP2 – experimental)............................................................21Put ‘unicode’ form (5.5 DP2)....................................................................................................22

MacOS X Ask / Answer File Dialog..............................................................................................22textStyle Property Array Variant (5.0.2 – experimental)...........................................................22

Mac – revCapture video capture library (4.6.1 – experimental )...................................................22Session management................................................................................................................. 23Input configuration....................................................................................................................23

1


Querying available inputs.....................................................................................................23Configuring the audio input................................................................................................. 23Configuring the video input................................................................................................. 24

Compression configuration....................................................................................................... 24Querying available codecs....................................................................................................24Configuring the audio codec................................................................................................ 24Configuring the video codec................................................................................................ 25

Preview management................................................................................................................ 25Configuring the video preview image.................................................................................. 25Configuring the audio preview volume................................................................................25Previewing a session............................................................................................................ 25

Record management..................................................................................................................26Configuring the output file................................................................................................... 26Configuring the maximum frame size..................................................................................26Configuring the maximum frame rate.................................................................................. 26Starting recording................................................................................................................. 26Stopping recording............................................................................................................... 27

XML text node access (4.6 – experimental).................................................................................. 27Ordered and unordered lists (4.6 – experimental)......................................................................... 28

Properties.................................................................................................................................. 28htmlText format.........................................................................................................................29rtfText format............................................................................................................................ 30plainText format........................................................................................................................ 30Persistence.................................................................................................................................30

Runtime execution stack configuration (4.5.1 – experimental).....................................................30revBrowser windowId property (4.5.1 – experimental)................................................................ 31Improved image export (4.5)......................................................................................................... 31

Raw data export (experimental)................................................................................................ 31Elevated process support (4.5 – experimental)..............................................................................32Status icon support (4.5 – experimental)....................................................................................... 32Listing sub-keys in the registry (4.5 – experimental).................................................................... 33HTTPS – automatic root certificate discovery (4.5 – experimental).............................................34Mac – dock icon support (4.5 – experimental).............................................................................. 34

Choosing an image....................................................................................................................34Configuring the dock icon menu...............................................................................................34Specific bug fixes (5.5.1).......................................................................................................... 35Specific bug fixes (5.5)............................................................................................................. 36

IDE Changes.......................................................................................................................................38Updates for new unicode and textStyle functionality (5.5 DP2)................................................... 38

Property Inspector................................................................................................................ 38Menu Builder........................................................................................................................38Menu - Edit > Text .............................................................................................................. 38

Getting folder locations within the IDE.........................................................................................38Standalone builder......................................................................................................................... 38

Windows – UAC Manifest........................................................................................................38Web........................................................................................................................................... 39

Datagrid......................................................................................................................................... 39Specific bug fixes (5.5.1).......................................................................................................... 40Specific bug fixes (5.5)............................................................................................................. 40

2


User Guide..................................................................................................................................... 40Dictionary...................................................................................................................................... 40Mobile Examples........................................................................................................................... 40

Previous Release Notes...................................................................................................................... 41Revisions............................................................................................................................................ 41

3


OverviewLiveCode 5.5.1 is an update to 5.5, introducing mobile advertising support and numerous bug fixes.

This document describes all the changes that have been made – including bug fixes and new syntax.

For information about improvements made to the iOS port of the engine, please see the iOS Release Notes PDF.

For information about improvements made to the Android port of the engine, please see the Android Release Notes PDF.

At the time of writing, this information has yet to been integrated into the dictionary or User's Guide.

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.

Platform supportThe 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

The engine supports the following Windows OSes:

• Windows 2000 SP4

• Windows XP SP2 and above

• Windows Server 2003

• Windows Vista SP1 and above (both 32-bit and 64-bit)

• Windows 7 (both 32-bit and 64-bit)

• Windows Server 2008

Note: On 64-bit platforms the engine still runs as a 32-bit application through the WoW layer.

Linux

The linux engine requires the following:

• 32-bit installation, or a 64-bit linux distribution that has a 32-bit compatibility layer

• 2.4.x or later kernel

• X11R5 capable Xserver running locally on a 24-bit display

• glibc 2.3.2 or later

4


• gtk/gdk/glib (optional – required for native theme support)

• pango/xft (optional – required for pdf printing, anti-aliased text and unicode font support)

• lcms (optional – required for color profile support in JPEGs and PNGs)

• gksu (optional – required for elevate process support)

Note: The optional requirements (except for gksu and lcms) are also required by Firefox and Chrome, so if your linux distribution runs one of those, it will run the engine.

Note: If the optional requirements are not present then the engine will still run but the specified features will be disabled.

Note: LiveCode and standalones it builds may work on remote Xservers and in other bit-depths, however this mode of operation is not currently supported.

Mac

The Mac engine supports:

• 10.4.11 (Tiger) on Intel and PowerPC

• 10.5.8 and later (Leopard) on Intel and PowerPC

• 10.6.x (Snow Leopard) on Intel

• 10.7.x (Lion) on Intel

Note: The engine runs as a 32-bit application regardless of the capabilities of the underlying processor.

Proposed changes

The following changes are likely to occur in the next or subsequent non-maintenance release:

• The engine (both IDE and standalone) will require gtk, gdk, glib, pango and xft on Linux

5

Setup

Installation

The structure of the IDE install has changed significantly in this release.

Each distinct version has its own complete folder – multiple versions will no longer install side-by-side: on Windows (and Linux), each distinct version will gain its own start menu (application menu) entry; on Mac, each distinct version will have its own app bundle.

The default location for the install on the different platforms when installing for 'all users' are:

• Windows: <x86 program files folder>/RunRev/ LiveCode 5.5.1

• Linux: /opt/runrev/livecode-5.5.1

• Mac: /Applications/ LiveCode 5.5.1.app

The default location for the install on the different platforms when installing for 'this user' are:

• Windows: <user roaming app data folder>/RunRev/Components/LiveCode 5.5.1

• Linux: ~/.runrev/components/livecode-5.5.1

• Mac: ~/Applications/ LiveCode 5.5.1.app

Note: If your linux distribution does not have the necessary support for authentication (gksu) then the installer will run without admin privileges so you will have to manually run it from an admin account to install into a privileged location.

Uninstallation

On Windows, the installer hooks into the standard Windows uninstall mechanism. This is accessible from the appropriate pane in the control panel.

On Mac, simply drag the app bundle to the Trash.

On Linux, the situation is currently less than ideal:

• open a terminal

• cd to the folder containing your rev install. e.g.

cd /opt/runrev/livecode-5.5.1

• execute the .setup.x86 file. i.e.

./.setup.x86

• follow the on-screen instructions.

Reporting installer issues

If you find that the installer fails to work for you then please file a bug report in the RQCC or email [email protected] so we can look into the problem.

In the case of failed install it is vitally important that you include the following information:

6

mailto:[email protected]

• Your platform and operating system version

• The location of your home/user folder

• The type of user account you are using (guest, restricted, admin etc.)

• The installer log file located as follows:

• Windows 2000/XP: <documents and settings folder>/<user>/Local Settings/

• Windows Vista/7: <users folder>/<user>/AppData/Local/RunRev/Logs

• Linux: <home>/.runrev/logs

• Mac: <home>/Library/Application Support/Logs/RunRev

Activation

The license system has been replaced in this release.

The new 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.

Multi-user and network install support (4.5.3)

In order to better support institutions needing to both deploy the IDE to many machines and to license them for all users on a given machine, a number of facilities have been added which are accessible by using the command-line.

Note: These features are intended for use by IT administrators for the purposes of deploying LiveCode in multi-user situations. They are not supported for general use.

Command-line installation

It is now possible to invoke the installer from the command-line on both Mac and Windows. When invoked in this fashion, no GUI will be displayed, configuration being supplied by arguments passed to the installer.

On both platforms, the command is of the following form:

<exe> install noui options

Here options is optional and consists of one or more of the following:

-allusers Install the IDE for all users. If not specified, the install will be done 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 location to install into. If not specified, the location defaults to those

described in the Layout section above.

7

-log logfile A file to place a log of all actions in. If not specified, no log is generated.Note that the command-line variant of the installer does not do any authentication. Thus, if you wish to install to an admin-only location you will need to be running as administrator before executing the command.

As the installer is actually a GUI application, it needs to be run slightly differently from other command-line programs.

In what follows <installerexe> should be replaced with the path of the installer executable or app (inside the DMG) that has been downloaded.

On Windows, you need to do:

start /wait <installerexe> install noui options

On Mac, you need to do:

“<installerexe>/Contents/MacOS/installer” install noui options

On both platforms, the result of the installation will be written to the console.

Command-line activation

In a similar vein to installation, it is now possible to activate an installation of LiveCode for all-users of that machine by using the command-line. When invoked in this fashion, no GUI will be displayed, activation being controlled by any arguments passed.

On both platforms, the command is of the form:

<exe> activate -file license -passphrase phrase

This command will load the manual activation file from license, decrypt it using the given passphrase and then install a license file for all users of the computer. Manual activation files can be downloaded from the 'My Products' section of the RunRev customer accounts area.

This action can be undone using the following command:

<exe> deactivate

Again, as the LiveCode executable is actually a GUI application it needs to be run slightly differently from other command-line programs.

In what follows <livecodeexe> should be replaced with the path to the installed LiveCode executable or app that has been previously installed.

On Windows, you need to do:

start /wait <livecodeexe> activate -file license -passphrase phrase

start /wait <livecodeexe> deactivate

On Mac, you need to do:

“<livecodeexe>/Contents/MacOS/LiveCode” activate -file license -passphrase phrase

“<livecodeexe>/Contents/MacOS/LiveCode” deactivate

8


On both platforms, the result of the activation will be written to the console.

9

Engine ChangesImportant: As of 5.5-dp-3, the default stack file format has been updated to 5.5. The previous default version (2.7) has been set as a legacy option in the “Save As” dialog. As such, the field updates added in 5.5 are now no longer considered experimental.

Warning: File Format changes to LiveCode 5.5 mean stacks created in LC 5.5 DP2 and above could have data loss if opened in older versions (field style related data)

The unicodeToolTip property (5.5 RC1)

A new property unicodeToolTip has been added. This property allows unicode text to be diplayed in tooltips and functions in exactly the same was as the toolTip, except that it expects a UTF-16 encoded string, rather than a native encoded string.

Paragraph hiding (5.5 DP3)

There is a new hidden paragraph attribute. When set to true, the given paragraph will not be drawn nor take part in any vertical height calculations - essentially hiding it from view.

The paragraph’s content still remains in the text buffer and will be included in any requested chunks assuming it is in range.

When exported as a styledText array, if a paragraph is hidden then the corresponding paragraph array will have a hidden key with value true.

Updated htmlText (5.5 DP3)

The htmlText content format has been updated. It is now a fully faithful representation of field content, and includes all the new paragraph styles introduced in 5.5. Note that there have been a few minor changes to the format relative to previous versions.

Sequences of paragraphs with the listStyle attribute set will be encased by appropriate ordered/unordered list tags - <ul> for unordered (bulleted) styles and <ol> for ordered (enumerated) styles. The paragraph (or paragraphs if the skip listStyle is present) associated with each list item is encased inside an <li> tag.

Each paragraph will be encased by ... tags. The tag can have zero or more of the following attributes: align, firstindent, leftindent, rightindent, spaceabove, spacebelow, tabstops, bgcolor, borderwidth, hgrid, vgrid, bordercolor, dontwrap, padding, hidden.

The character level styles applied to runs of text in paragraphs are represented using the following tags:

• textShift: if negative uses the <super> tag otherwise uses the tag; in either case the value of the textShift property is present as a shift attribute.

• textFont, textSize, textColor, backgroundColor: combined into a tag with one or more attributes face, size, color, bgcolor.

• textStyle: map to the , , <strike>, , <condensed>, <expanded>, <threedbox>, <box> tags as appropriate.

• linkText: maps to an <a> tag with name attribute if no link textStyle set, or href otherwise.

10

• metadata: maps to a tag with metadata attribute.

• imageSource: maps to an <img> tag with src attribute and char attribute. The char attribute contains the character the image replaces in the field.

The text encoding of the content is ASCII so any non-ASCII characters are encoded using the standard HTML entities as far as possible; any remaining non-ASCII characters being represented as numeric entities (&#<d>;).

Updated rtfText (5.5 DP3 – Updated 5.5 RC1)

The rtfText content format has been updated to include the new paragraph attributes added in 5.5. In addition a number of issues have been resolved:

• font sizes now map correctly to points.

• links (linkText together with link textStyle) now appear as HYPERLINK fields.

• the cb and chchpat tags are now used to specify character-level background color (instead of highlight).

Note that rtfText is an effective format and is not fully faithful.

As of 5.5-rc-1, importing rtfText supports the new paragraph attributes.

Unlinking of text properties in objects (5.5 DP2)

Similar to field chunks, in previous engine setting one of the textFont, textSize, textStyle or textHeight properties on an object would cause all four to be set if they had not already been previously; the values being inherited from the parent.

This behavior has also been changed in 5.5. The engine now allows all these properties to be set individually (textHeight has special rules - see below).

This change is persistent for stacks that are saved in 5.5 and then reloaded into 5.5 and later. If a stack saved in 5.5 is loaded into an earlier engine then the separation of these properties will be lost and it will appear as it would had the properties been set in that engine. (i.e. Any unset properties in the stackfile will transpire as properties set to the nearest ancestor’s values).

Note that textHeight is always set when textSize is set, and if textHeight is not set then it will be calculated from the effective textSize. So, if you want to change the textHeight and textSize, set the textSize first, then set the textHeight.

Manipulating Unicode in objects (5.5 DP2)

In previous engines buttons, groups and graphics could use unicode text by marking the textFont property with a “,unicode” tag; this would cause the engine to interpret the text and label properties as UTF-16.

This behavior has changed in 5.5. The engine now treats the unicode nature of the text and/or label properties of buttons, groups and graphics as an intrinsic property that cannot be altered by script. In particular, putting UTF-16 text into a button then settings its textFont property to “,unicode” (or “,unicode”) will no longer have any effect.

11

To use unicode with these objects then use the following properties:

buttons: the unicodeText to set the menu description (if a menu); the unicodeLabel to the button label.

graphics: the unicodeLabel to set the graphic label.

groups: the unicodeLabel to set the group label.

To determine whether an object is currently storing its text and/or label as unicode there is a new read-only encoding property. This will return unicode if the engine is currently using UTF-16 to store the text/label, or native otherwise.

To fetch the current content/label of the object as native use the text or the label properties. This is a change from previous engines where these properties would return either native or UTF-16 text, depending on whether there was a “,unicode” tag in the (effective) textFont.

These changes are persistent for stacks that are saved in 5.5 and then reloaded into 5.5 and later. If a stack saved in 5.5 is loaded into an earlier engine then the textFont property of the object (and other text properties) will be set to have the effective textFont together with the (expected) “,unicode” tag

New Field Features

Flagged char ranges (5.5 DP1)

There is a character-level property flagged in fields.

Runs of characters that have this property set to true will be underlined with a dotted red line, flagging them as potentially needing attention. The purpose of this property is to allow easier implementation of on-demand spell-checking in fields.

The flagged property differs from other character properties in that it is considered extra information that is not part of the styling of the field. This means that its value does not appear in, and has no effect on, any of the (persistent) content formats (styledText, rtfText, htmlText) nor will it appear when content is copied or pasted.

To make it easier to handle the flagged property (since it does not appear in any persistent form), there is a field and field chunk level property flaggedRanges. This property returns a return-delimited list of character ranges on which flagged is set to true. The character ranges are relative to the first index of the chunk the range is requested for.

For example, consider the following text (underline indicates the flagged ranges):

Hello LiveCode World

Goodbye LiveCode World

With this we get:

the flaggedRanges of field => 7,14<cr>30,37

the flaggedRanges of line 1 of field => 7,14

the flaggedRanges of line 2 of field => 9,16

The flaggedRanges is both settable and gettable. For example, the following has no resulting effect:

set the flaggedRanges of line 2 of field 1 to the flaggedRanges of line 2 of field 1

12

Note: The flagged property is useful as it gives a way of highlighting text which does not in any way effect the content. The flaggedRanges property is useful because it allows you to easily transfer the flagging between fields and portions of fields.

Chunk index conversion (5.5 DP1)

There are two field chunk properties charIndex and lineIndex.

These properties allow easy (and efficient) conversion between the character index at which a beginning of a line sits, and the line index in which a character sits.

The charIndex of a field chunk will return the character offset in the field of the start of the chunk.

The lineIndex of a field chunk will return the line offset in the field of the start of the chunk.

For example, consider the following text:

Hello World

Goodbye World

With this we get:

the charIndex of line 2 of field => 13

the lineIndex of char 7 of field => 1

the charIndex of word 2 of field => 7

Note that the charIndex property takes into account the Unicode nature of the chunk (if applicable) meaning that in some cases the charIndex of char 5 is not necessarily 5.

Note: This is useful because there are many places where the engine gives you a field chunk in char or line form, but you might want the the opposite indices. (e.g. the lineIndex of the selectedChunk gives you the index of the line containing the selection).

Metadata char property (5.5 DP1)

There is a new character-level property metadata in fields.

This property can be set on runs of characters and is intended to allow applications to store data attached to character ranges in fields that has no effect on engine processing.

The value of the metadata property is limited to non-binary strings at present.

Note: This is useful because it allows data to be associated with text in fields that moves automatically as the field is edited. While you could do something like this with the linkText property that already existed, setting the linkText has an effect on both the visual presentation and UI interaction of text in fields.

Individual textStyle manipulation (5.5 DP1)

The textStyle property of fields has been extended with array notation to allow easier manipulation of individual styles.

It is now possible to use expressions of the form:

the textStyle[<style>] of <chunk> of field

13

Where <style> is one of bold, condensed, expanded, italic, oblique, box, threedbox, underline, strikeout, link, group.

Such a property can be set to either true or false and will result in either that style being added (true), or removed (false) from the textStyle’s of each character in the range.

Getting the property will result in one of true, false, or mixed depending on whether the property is set on all chars in the chunk (true), unset on all chars in the chunk (false), or set on some and unset on others (mixed).

For example, consider the following text where the middle word is in italics:


Performing the following command will add bold style to the given range without affecting the setting of italic:

set the textStyle[“bold”] of char 3 to -3 of field to true

Results in:


Note: This is useful because previously there was no (straightforward) way to set text styles individually. Indeed, the textStyle property is a comma-separated list of styles applied to the character so if you set it to italic, it obliterates the bold setting (if present).

textChanged message (5.5 DP1)

The field will now dispatch a message textChanged whenever a user (or simulated user) action may have caused the content of the field to change.

In particular, the following actions will result in a textChanged message being sent:

• typing into the field (whether non-Unicode or Unicode text)

• using the type command to type into a field

• pasting text into a field (whether via built-in keyboard shortcut, or the paste command)

• cutting text from fields (whether via built-in keyboard shortcut, or the cut command)

• drag drop operations on fields

The message is sent immediately after the operation completes, but before a screen update has been requested - the corresponding update will occur at the end of the first command in the textChanged handler. This means that you can lock screen as the first line of the handler to delay the update (allowing you to modify the content of the field without any flicker).

To prevent potential for infinite recursion, calls to textChanged will not nest. That is to say that if a textChanged handler is being executed for a given field, another textChanged message will not be sent to to it should one be triggered.

The textChanged message will be sent after messages such as keyDown and pasteKey but before messages such as keyUp.

Note: This is useful because at the moment there is no simple way to react when something non-script based modifies the field, you have to hook into numerous messages. Indeed, some things (such as Unicode text entry) result in no notification at all.

14

Unicode-aware field chunks (5.5 DP1)

The field will now (internally) correctly compute character ranges for chunks regardless of whether the text in the chunk is native, Unicode or a mixture.

Essentially this means that you can set and get properties of chunks in fields without having to worry about handling unicode text specially.

For example, consider the following text:

Hello Кгыышфт World

Goodbye Γρεεκ World

Previously attempts to do things like:

set the textStyle of word 2 of line 1 of field to “bold”

set the backColor of line 2 of field to “red”

Would, generally, not work because the field would not take into account the (two-byte) unicode characters correctly.

It should be noted that care still needs to be taken when manipulating the text content of such chunks. The value of a chunk such as:

line 2 of field 1

Will still be the ‘mixed’ representation the engine has internally which cannot really be processed in script. If there is need to process the content of chunks then the text and unicodeText properties should be used:

the text of line 2 of field 1 => “Goodbye ????? World” (native text encoding)

the unicodeText of line 2 of field 1 => “Goodbye Γρεεκ World” (UTF-16 text encoding)

Notice that the text property converts the content to the native text encoding (MacRoman, Windows-1252, ISO-8859-1 depending on platform) with ‘?’ used for unconvertable characters; whereas the unicodeText property returns the content of the chunk as (uniform) UTF-16.

Note: This is useful because it enables many operations on fields to be performed regardless of whether the field contains Unicode text. Previously it was (basically) impossible to do anything with field chunks if the field contained Unicode text.

styledText content format (5.5 DP1 )

The field now has a new ‘content’ format - styledText. This is similar to rtfText and htmlText in that it provides a script-processable representation of the field’s content. It differs from these two formats in two ways: it is a fully faithful representation (set the styledText of field to the styledText of field results in no change to the field); it is array-based.

The styledText property returns a numerically-indexed array of paragraphs, each index representing each paragraph in the field in order:

tStyledTextArray[1] = <first paragraph array>

…

tStyledTextArray[<n>] = <last paragraph array>

15

Each paragraph array has up to two keys:

tParagraphArray[“style”] = <array containing paragraph-level styles>

tParagraphArray[“runs”] = <paragraph content array>

The style array contains the values for each of the paragraph styles set on that paragraph. The list of styles that are supported are: textAlign, listStyle, listDepth, listIndent, firstIndent, leftIndent, rightIndent, spaceAbove, spaceBelow, tabStops, backgroundColor, borderWidth, borderColor, hGrid, vGrid, dontWrap and padding.

The paragraph content array is a numerically-indexed array of runs, each index representing each run in the paragraph in order:

tParagraphContentArray[1] = <first paragraph run array>

…

tParagraphContentArray[<n>] = <last paragraph run array>

Each paragraph run array has up to three keys:

tRunArray[“style”] = <array containing character-level styles for the run>

tRunArray[“metadata”] = <metadata of the run (if present)>

tRunArray[“text” (or “unicodeText”)] = <text content of run>

The style array contains the values for each of the characters styles set on that run. The list of styles that are supported are: textFont, textSize, textStyle, textColor, backgroundColor, linkText and imageSource.

If a run has Unicode text in it then the run array will have a “unicodeText” key containing its content encoded as UTF-16. Otherwise, the run array will have a “text” key containing its content encoded in the native text encoding.

For example, take the following content consisting of two paragraphs:

Centered Hello World

Left-aligned Hello Цщкдв

This would transpire as the following array:

1 =>

style = { textAlign => “center” }

runs =>

1 = { text => “Centered “ }

2 =>

style = { textStyle => “bold” }

text = “Hello”

3 = { text => “ World” }

2 =>

runs =>

16


1 = { text => “Left-aligned “ }

2 =>

style = { textColor => “255,0,0” }

text = “Hello”

3 = { unicodeText => “ Цщкдв” }

[ For brevity, single element arrays are represented using { … } notation ]

When setting the styledText property, the engine uses a very permissive algorithm to parse the arrays as follows:

parseStyledTextArray pStyledText

repeat for each element tEntry of pStyledText

if tEntry is a sequence then

parseStyledTextArray tEntry

else if tEntry has key "runs" then

begin paragraph with style tEntry["style"]

parseStyledTextRunArray tEntry["runs"]

end paragraph

else if tEntry is an array then

append tEntry["text"] with style tEntry["style"]

parseStyledTextRunArray pRun

repeat for each element tRun in pRuns

if tRun is a sequence then

parseStyledTextRunArray tRun

else

append tRun["text"] with style tEntry["style"]

The engine flattens any nested numeric arrays within the tree; then iterates through the result ignoring any empty entries. If an array has a 'runs' key it is treated as an independent paragraph; otherwise it is assumed to be a 'run' and the styled text it contains is appended to the current paragraph. Note that the 'text' field of a run can contain newlines the presence of which will cause a paragraph break at the appropriate points - if such a break is made, the paragraph attributes will be copied across the break.

Note: This property is useful because it provides a easily manipulable representation of the field contents. In particular as it is array-based it allows much easier modification of specific parts of the field than having to manipulate the string-based htmlText and rtfText.

17


Hierarchical list support (5.5 DP1)

The engine now has support for hierarchical lists in fields. These are controlled with the listStyle, listDepth and listIndent paragraph-level properties.

The listStyle property determines what kind of index is displayed for the paragraph. It can be one of the following: disc, circle, square, decimal, lower latin, upper latin, lower roman, upper roman and skip.

The disc, circle and square settings cause the paragraph to be displayed with a bullet; while the decimal, lower/upper latin and lower/upper roman settings cause the paragraph to be displayed with its index written in the specified way (number, alphabetic or roman numerals). The index of a paragraph is computed as the number of preceeding paragraphs with the same listStyle before a paragraph is encountered with the same or lesser listDepth and different listStyle. In particular, this rule means that indexing continues after nested lists in the way you would expect.

The skip setting causes the paragraph to be displayed with an empty label - such paragraphs are ignored when computing the index of other paragraphs allowing it to be used to display multiple paragraphs in the same list item.

The listDepth property is a number between 1 and 16 which determines the nesting depth of the list. The depth of a list is used to compute the paragraph’s list index as well as the indentation (if firstIndent is not set).

The listIndent property determines the amount to indent the content of the paragraph by for each level of depth. If the firstIndent property of the paragraph is set instead, the engine uses firstIndent together with leftIndent to determine the placement of the label and content - in this case, the listDepth is ignored.

For example:

• listStyle = disc, listDepth = 1, listIndent = 20 (so text starts at 20)

a) listStyle = lower latin, listDepth = 2, listIndent = 20 (so text starts at 40)

b) listStyle = lower latin, listDepth = 2, listIndent = 20 (so text starts at 40)

i. listStyle = lower roman, listDepth = 3, listIndent = 20 (so text starts at 60)

c) listStyle = lower latin, listDepth = 2, listIndent = 20 (so text starts at 40)

Note: This is useful as it makes it easy to display (and allow the user to edit) nested lists with automatic labelling.

Paragraph level properties (5.5 DP1)

The engine now has support for paragraph-level properties. Some existing field-level properties have been lifted to the paragraph-level, alongside several new properties for controlling the display of paragraphs.

The available paragraph-level properties are as follows: textAlign, listStyle, listDepth, listIndent, firstIndent, leftIndent, rightIndent, spaceAbove, spaceBelow, tabStops, backgroundColor, borderWidth, borderColor, hGrid, vGrid and dontWrap.

The textAlign property allows the alignment of a paragraph to be set independently. It can be one of

18


left, center, right. If the property is not set on a paragraph, the setting is inherited from that of the field.

The firstIndent property determines how much to indent the first line of a paragraph. The indent is considered to be relative to the leftIndent setting of the paragraph so positive values shorten the first line whereas negative values lengthen the first line. [ Note that in the case of a paragraph with non-empty listStyle, the firstIndent property (if set) determines the offset of the label relative to the start of the text and (in that case) must be negative. ]

The leftIndent and rightIndent properties determine how much space to leave at either side of the paragraph before any border and content is rendered.

The spaceAbove and spaceBelow properties determine how much space to leave above and below the paragraph before any border and content is rendered.

The tabStops property allows tab-stops to be set on a per-paragraph basis. If the property is not set on a paragraph, the tabStops setting of the field is used.

The backgroundColor property allows the color of the content area (inside any paragraph border) to be filled (note that strictly speaking this property is not inherited, but the effect is the same as if it was as the background of the field is rendered before the paragraphs are so the background color at the field level will ‘show through’ to the paragraph if the paragraph has no background color).

The borderWidth property determines the width of the border to draw around the paragraph.

The padding property determines the amount of space between the border and the text content. In vGrid mode, each cell is reduced in width to accomodate the padding at either end of the cell (i.e. it provides padding in each cell in addition to around the line as a whole).

The borderColor property determines the color to use when drawing the border and grid (if either of the grid properties are set). The borderColor is inherited from the field if not set on the paragraph.

The hGrid property controls automatic generation of grid lines between paragraphs. If the hGrid is set to true on a paragraph (or inherits the true setting from the field) then an implicit 1 pixel wide border will be placed both above and below the paragraph. Additionally, the engine will elide borders of adjacent paragraphs which have hGrid set to true if their properties are compatible. Specifically, if two adjacent paragraphs have hGrid set, have the same borderWidth and no (or 0) spaceAbove and spaceBelow, a single pixel grid line will be placed between them rather than the normal border.

The vGrid property allows automatic generation of grid lines between tabs and cell clipping to be set on a per-paragraph basis. If the property is not set at the paragraph level it’s value is inherited from the field.

The dontWrap property allows line-wrapping to be set on a per-paragraph basis. If the property is not set at the paragraph level it’s value is inherited from the field.

Note: These features are useful for obvious reasons. In particular, the paragraph-level indents, borders and back-colors make it much easier to develop well styled text content; and the paragraph-level hGrid, vGrid and tabStops enable simple tables to be embedded inbetween normal paragraphs.

vGrid column visibility and tabWidths (5.5 DP1)

It is now possible to hide individual columns when vGrid is in effect. The engine will skip any

19


columns which have an effective tabStop width of 0. For example, suppose you want a table-like layout with columns of 50 wide but with the first and third columns hidden. You can use the following tabStops:

0,50,0,50

This means the first column is of zero width (hidden), the second is 50 wide, the third is of zero width (hidden) then all subsequent columns are 50 wide.]

To help with control column visibility a new (synthetic) property tabWidths has been added. This property is similar to the tabStops property except that it returns the tab stops as a sequence of widths rather than as absolute positions. For example, the following are equivalent:

tabStops = 50,100,150,200,250,250

tabWidths = 50,50,50,50,50,0

Note: This feature is useful as it allows ‘hidden’ information to be stored in simple tables in fields on a per-row basis. The tabWidths property makes controlling visibility of individual columns much easier, as the relevant item can just be replaced with 0.

vGrid fixed width table mode (5.5 DP1)

When vGrid is in effect, if the final tabStop has 0 width the engine treats the paragraph as a fixed width table, the width being the position of the final tabstop.

In this mode, the width of the paragraph is considered to be the (fixed) width and this width is used to do the following:

• compute the placement of the table in the line taking into account the textAlign property

• compute the background rectangle to fill with the backColor property

• compute the placement of the border (if any)

In this mode, rather than borders and background fill going from left margin to right margin, they will instead go from left of the table to right of the table.

For example, suppose you want a table-like layout with only 5 columns of 50 wide. You can use the following tabStops:

50,50,50,50,50,0

This will result in a table of width 250 pixels.

Note: This feature is useful as it allows the number of columns to be explicitly specified (usually tabs continue for the entire width of the field) and then use the explicit width to place the table in the line allowing easy centering of simple tables within fields.

Unicode handling changes (5.5 DP2)

In previous engines, a sequence of unicode characters in a field was marked by having a “,unicode” tag in the textFont property of that run and the text of the field would contain mixed sequences of native encoded characters and UTF-16 encoded characters.

Both these behaviors have changed in 5.5. The engine now treats the unicode nature of a bytes in fields as an intrinsic property that cannot be altered by script. In particular, setting the text property of a field and then setting the textFont to “,unicode” will no longer have any effect.

20


Putting unicode text into a field can now only be done by setting the unicodeText property of the field (or a chunk of the field); using one of the content format properties such as rtfText, styledText or htmlText; or by a user action which causes unicode text to be entered into the field such as typing with a unicode IME.

The textFont property will no longer contain any ‘language’ tag, and setting the textFont of a chunk to one containing such a tag will result in the tag being stripped and ignored.

To determine whether a chunk in a field is encoded as either entirely unicode, entirely native or a mixture of the two there is a new read-only encoding property. [ Note that this property, currently, only reports whether text happens to be currently encoded in unicode, native or a mixture - not whether the text needs to be unicode, it is possible for runs of text that could be natively encoded to be encoded in unicode if that’s how it was placed in the field ].

As a result of these changes, the text property of a field returns the content in the native encoding. Similarly, when using a field as a destination or source in a chunk expression without using any of the ‘text’ properties, any chunk value will be natively encoded. i.e.

field 4 -- native

line 5 to 10 of field 3 -- native

the unicodeText of word 10 to 100 of field 2 -- unicode

Note that by separating out the unicode marker and textFont property it means that the textFont of a run can be set (and inherited!) independently of whether it is unicode or not. This change is persistent for stacks that are saved in 5.5 and then reloaded into 5.5 or later. If a stack saved in 5.5 is loaded into an earlier engine then, for runs which are unicode, the textFont property will be the inherited textFont together with the (expected) “,unicode” tag.

Unlinking of text properties in fields (5.5 DP2)

In previous engines, setting one of the textFont, textSize or textStyle properties on a field chunk would cause all three to be set if they had not already been previously; the values being inherited from the parent. This meant that once you’d set one of the properties, the other two would no longer inherit from an ancestor.

This behavior has been changed in 5.5. The engine now allows these properties to be set individually, and thus they all inherit individually. i.e. If the textFont is set on a run of text in a field, changing say the field’s textSize property will result in the run of text with differing textFont inheriting the new size automatically.

This change is persistent for stacks that are saved in 5.5 and then reloaded into 5.5 and later. If a stack saved in 5.5 is loaded into an earlier engine then the separation of these properties will be lost and in that engine, any runs of text with one or two of the properties set will have all set (the others being inherited from an appropriate ancestor).

Explicit line-breaks in fields (5.5 DP2 – experimental)

The engine will now interpret a numToChar(11) character in a field paragraph as an explicit line-break when the (effective) dontWrap of the paragraph is false. This allows multiple ‘lines’ to be displayed within a single paragraph.

The formattedText property has been updated to map any explicit line breaks to newlines.

21

Note that since the vGrid property turns dontWrap on for the paragraph, using the line-break char in table paragraphs will have no effect.

Put ‘unicode’ form (5.5 DP2)

There is a new variant of the put command:

put unicode <expr> [ into | before | after ] <field chunk>

Here <expr> is any LiveCode expression that evaluates to a (binary) string; and <field chunk> is any chunk that resolves to a field (or portion of a field).

This command is equivalent to:

put <expr> [ into | before | after ] <field chunk>

Except that <expr> is treated as UTF-16 encoded text; rather than native encoded text.

For example, to build up a sequence of lines in a field where each line is Unicode you can do:

put unicode tMyUTF16Line1 after field 1

put return after field 1

put unicode tMyUTF16Line2 after field 1

…

MacOS X Ask / Answer File Dialog

The MacOS X ask and answer file dialogs have been updated to use the Cocoa API.

textStyle Property Array Variant (5.0.2 – experimental)

A new array variant of the textStyle property has been added allowing for access to individual textStyles independently from the others by specifying the required style as an array key.

the textStyle[<style>]

Here, style can be one of bold, condensed, expanded, italic, oblique, box, threedbox, underline, strikeout, link.

Important: The features described above are experimental. This means that it may not be complete, or may fail in some circumstances that you would expect it to work. Please do not be afraid to try it out as we need feedback to develop it further.

Mac – revCapture video capture library (4.6.1 – experimental )

The revCapture library is begin developed as a replacement for revVideograbber – utilising the most up to date APIs on each platform, and eliminating many issues the previous library had (including problems introduced by Apple with iSight video-capture in 10.6.5 onwards).

At this time, the revCapture library is Mac-only, and is integrated as part of the revVideograbber external; it will be moved into its own external and become cross-platform over time.

While largely similar in function to revVideograbber, the revCapture library does have a number of differences:

22


• There are no configuration dialogs – instead, available inputs and codecs can be queried and configured through script.

• Previewing and recording can be started and stopped independently.

• Previewing takes place direct into a (configurable) image object, allowing the preview to be rendered with effects, blending, inks and interleave with other objects.

• Only supports output to QuickTime MOV files with a limited collection of preconfigured codecs.

The available handlers are described in the following sections.

Note: As it stands the revCapture library has only been tested with built-in iSight hardware, although there is no reason it shouldn't work with any hardware that QTKit supports.

Important: This feature is currently experimental. This means that it may not be complete, or may fail in some circumstances that you would expect it to work. Please do not be afraid to try it out as we need feedback to develop it further.

Session management

All capture operations take place within a capture session, which is managed using:

revCaptureBeginSession

revCaptureEndSession

Call revCaptureBeginSession to initialize the capture session, allowing the rest of the capture library to be used. When the capture session is done with, call revCaptureEndSession. This will release any hardware, and cancel any recording and previewing operations.

Note: Calling any of the revCapture functions without calling revCaptureBeginSession at some point before hand will cause a no session error to be thrown.

Input configuration

Unlike revVideograbber, configuration of the inputs to use for video/audio capture is done entirely through script rather than invoking standard dialogs.

Querying available inputs

To query the currently available inputs capable of capturing audio or video data use:

revCaptureListAudioInputs()

revCaptureListVideoInputs()

These both return a newline-delimited list of the available inputs of the given type.

Configuring the audio input

To configure the audio input to capture from in the current session, use:

revCaptureGetAudioInput()

revCaptureSetAudioInput audioInput

23


Where audioInput is one of:

• the name of an input returned by revCaptureListAudioInputs()

• default, indicating the default audio input device on the system should be used

• none, indicating that no audio should be captured

If setting an audio input fails because the new device could not be accessed, a could not open input error is thrown. If the current session could not connect to the new device, a could not connect to input error is thrown.

Configuring the video input

To configure the video input to capture in the current session, use:

revCaptureGetVideoInput()

revCaptureSetVideoInput videoInput

Where videoInput is one of:

• the name of an input returned by revCaptureListVideoInputs()

• default, indicating the default video input device on the system should be used

• none, indicating that no video should be captured

If setting an audio input fails because the new device could not be accessed, a could not open input error is thrown. If the current session could not connect to the new device, a could not connect to input error is thrown.

Compression configuration

Similar to input configuration, choosing the codec to use when recording audio and video streams is done entirely through script.

Querying available codecs

To query the currently available codecs for audio or video recording use:

revCaptureListAudioCodecs()

revCaptureListVideoCodecs()

These both return a newline-delimited list of the available codecs of the given type.

Configuring the audio codec

To configure the audio codec to use when recording, use:

revCaptureGetAudioCodec()

revCaptureSetAudioCodec audioCodec

Where audioCodec is either none to indicate that no audio compression should be performed, or the name of a codec returned by revCaptureListAudioCodecs().

If the given codec name is unrecognized, or is not suitable for audio compression then an invalid

24


codec for media type error is thrown. If recording is currently happening, a recording in progress error is thrown.

Configuring the video codec

To configure the video codec to use when recording, use:

revCaptureGetVideoCodec()

revCaptureSetVideoCodec videoCodec

Where videoCodec is either none to indicate that no video compression should be performed, or the name of a codec returned by revCaptureListVideoCodecs().

If the given codec name is unrecognized, or is not suitable for video compression then an invalid codec for media type error is thrown. If recording is currently happening, a recording in progress error is thrown.

Preview management

Configuring the video preview image

In order to be able to see a video preview of a capture session, the long id of an image object to target needs to be provided. To manage this use:

revCaptureGetPreviewImage()

revCaptureSetPreviewImage imageLongId

Where imageLongId is the long id of an existing empty image object to use; or empty to turn off the preview image.

Setting the preview image will lock the corresponding object meaning it can't be resized or have it's content modified by anything apart from the capture session. If the image cannot be found, locked, or an offscreen buffer initialized a suitable error will be thrown.

Configuring the audio preview volume

To configure the volume of the audio preview of a capture session use:

revCaptureGetPreviewVolume()

revCaptureSetPreviewVolume newVolume

Where newVolume is an integer between 0 (no audio preview) and 100 (audio preview at maximum volume).

Previewing a session

To start or stop a preview from running use:

revCaptureStartPreviewing

revCaptureStopPreviewing

The status of the preview is independent to that of recording, meaning that you can preview without recording, and record without previewing.

25


If a preview of the session could not be initialized when calling revCaptureStartPreviewing a could not connect to output error is thrown.

Note: Starting to record may have an effect on the video preview's aspect and frame size as the video capture pipeline is optimized by the system based on the needs of the recorded output.

Record management

Configuring the output file

To configure the filename to use when recording a capture session use:

revCaptureGetRecordOutput()

revCaptureSetRecordOutput recordFilename

Where recordFilename is an (absolute) path to the file to use for recording.

If recording is currently in progress, a recording in progress error is thrown.

Configuring the maximum frame size

To configure the maximum size of a frame in the recorded file use:

revCaptureGetRecordFrameSize()

revCaptureSetRecordFrameSize maxWidth, maxHeight

Where maxWidth and maxHeight specify the maximum size of a frame (in pixels) that should be generated in the (compressed) output. To use the default (optimal) frame size for the current settings, specify both width and height as 0.

Note: These act as a hint to the pipeline, and the actual size of the frames in the output file may be smaller than this, or have a different aspect ratio.

Configuring the maximum frame rate

To configure the maximum frame rate to aim for in the recorded file use:

revCaptureGetRecordFrameRate()

revCaptureSetRecordFrameRate maxFrameRate

Where maxFrameRate is the number of frames per second to aim for. To use the default (optimal) frame rate for the current settings, specify the rate as 0.

Note: This acts as a hint to the pipeline as to the rate to aim for. The resulting frame rate in the recorded file may be less than, or more than this setting.

Starting recording

To start recording the current session use:

revCaptureStartRecording

This configures the session with previously selected record options and codecs, deletes the currently specified output file (if present) and starts the recording process. It has no effect if the session is already being recorded.

26

If recording starts successfully, the result is empty.

If an error occurs when the output file is being prepared for recording, the result will contain recording failed.

If the session could not be configured for recording, a could not connect to output error is thrown.

Stopping recording

To stop recording the current session use:

revCaptureStopRecording

This finishes outputting any pending samples to the output file and stops recording. It has no effect if the session is not currently being recorded.

If recording finished successfully, the result is empty.

If an error occurs while trying to finish writing the output file, the result will contain recording failed.

XML text node access (4.6 – experimental)

Support has been added to some revXML functions for manipulating text nodes. Consider the following XML fragment:

<summary>

Removes a <keyword>message</keyword> that was queued with the <command>send</command> command and is waiting to be sent.

<summary>

This has the following structure as an XML tree:

ELEMENT(summary)

TEXT(Removes a)

ELEMENT(keyword)

TEXT(message)

TEXT( that was queued with the )

ELEMENT(command)

TEXT(send)

TEXT( command and is waiting to be sent.)

Notice that the named XML nodes, are interspersed with (essentially unnamed) nodes containing text content. These (previously unaccessible) nodes can now be accessed (with some functions) by using a path of the form:

<parent>/[<index>]

Here this references the <n>th text node under <parent>. For example, the above tree has the following accessible nodes:

summary/[1]

27


summary/keyword

summary/keyword/[1]

summary/[2]

summary/command

summary/command/[1]

summary[3]

To access text content of a node simply use the revXMLNodeContents function with this extended path format. Note that the previous behavior is preserved – if you specify a node with a '/[n]' suffix, the text content of the node will be returned (if it is a text node). (i.e summary/keyword and summary/keyword/[1] are the same thing to revXMLNodeContents).

The following functions have been augmented with an additional (optional) parameter incText:

revXMLFirstChild(docId, [ incText ])

revXMLNextSibling(docId, nodePath, [ incText ])

revXMLPrevSibling(docId, nodePath, [ incText ])

revXMLChildNames(docId, nodePath, delimiter, filter, incCounts, [ incText ])

Here if incText is specified and is true, the functions will include text nodes in their processing.

For example, this allows you to loop over all nodes including text nodes using something like:

local tCurrentNode

put revXMLFirstChild(tDocId, tParentNode, true) into tCurrentNode

repeat while tCurrentNode is not empty

... use tCurrentNode ...

put revXMLNextSibling(tDocId, tCurrentNode, true) into tCurrentNode

end repeat


Ordered and unordered lists (4.6 – experimental)

Properties

Experimental support has been added to the field for simple, single level, ordered and unordered lists. To make a paragraph display as an element in a list use the listStyle property:

set the listStyle of line lineIndex of field to style

Where style is one of:

• disc – the paragraph is rendered as an element in an unordered list with the standard bullet character as marker (U+2022).

28

• circle – the paragraph is rendered as an element in an unordered list using the (unicode) character U+25E6 as marker.

• square – the paragraph is rendered as an element in an unordered list using the (unicode) character U+25AA as marker.

• decimal – the paragraph is rendered as an element in an ordered list, the label using standard (Arabic) decimal numerals. i.e. 1, 2, 3, 4, etc.

• lower latin – the paragraph is rendered as an element in an ordered list, the label using lowercase (Latin) letters. i.e. a, b, c, …, aa, ab, etc.

• upper latin – the paragraph is rendered as an element in an ordered list, the label using uppercase (Latin) letters. i.e. A, B, C, …, AA, AB, etc.

• lower roman – the paragraph is rendered as an element in an ordered list, the label using lowercase Roman numerals. i.e. i, ii, iii, iv, …, etc.

• upper roman – the paragraph is rendered as an element in an ordered list, the label using lowercase Roman numerals. i.e. I, II, III, IV, …, etc.

For both ordered and unordered list the marker is placed at the first tab-stop, and the content of the paragraph is placed (and wraps) at the second tab-stop.

For ordered lists the index of the item is determined by the number of preceding paragraphs with the same listStyle property.

Setting the listStyle property of a paragraph to empty causes it to revert to a normal (non-list item) paragraph.

htmlText format

Paragraphs with a non-empty listStyle present themselves in htmlText wrapped with <LI> tags. Sequences of such paragraphs with the same listStyle are bracketed by <UL> or <OL> tags. These tags take a type attribute, matching the (legacy) HTML attribute of the same name:

• disc → disc

• circle → circle

• square → square

• 1 → decimal

• a → lower latin

• A → upper latin

• i → lower roman

• I → upper roman

For example:

1. Numbered Item 12. Numbered Item 2• Bulleted Item 1• Bulleted Item 2

<ol type='1' ><li>Numbered Item 1</li><li>Numbered Item 2</li></ol><ul type='disc'><li>Bulleted Item 1</li>

29

<li>Bulleted Item 2</li></ul>

rtfText format

Paragraphs with a non-empty listStyle are appropriately marked in rtfText using both the (legacy) pn family of paragraph numbering tags and also with the new listtable tags.

By using both sets of tags a reasonable degree of interoperability is achieved with both TextEdit (and other Cocoa applications) on Mac, and Word and WordPad on Windows.

Note: Unfortunately, OpenOffice does not have particularly good rtf import / export capabilities (it doesn't even round-trip correctly through itself!) and thus copying / pasting of lists between LiveCode and OpenOffice will not work reliably or correctly.

plainText format

Paragraphs with a non-empty listStyle are appropriately exported in plain text form when using the plainText, unicodePlainText, formattedText and unicodeFormattedText properties.

For example, the above example would be rendered (for plainText) as:<tab>1.<tab>Numbered Item 1<return>

<tab>2.<tab>Numbered Item 2<return>

<tab>•<tab>Bulleted Item 1<return>

<tab>•<tab>Bulleted Item 2<return>

Persistence

As it stands the listStyle property does not save into the stack-file and will not do so until version 5.0 when the file format is revised (for various technical reasons, it is not possible to add this as a saveable property with the current stackfile format).

It is recommended that htmlText be used to save the content of fields in custom properties, for restoration on reload.

Important: This feature is currently highly experimental. This means that it may not be complete, fail in some circumstances that you would expect it to work, or change considerably before becoming final. Additionally, it might have problems or gotchas that make it significantly harder to use than other LiveCode features at this time.

Runtime execution stack configuration (4.5.1 – experimental)

In order to be able to more reliably control the maximum level of recursion, a new global property stackLimit has been introduced.

This property allows a script to set (in bytes) the maximum size of the (runtime) stack the engine uses for recursive computation. A change in the setting will only take effect when all currently executing handlers complete, and at this time the stack size limit will be reconfigured to the given limit, or the nearest amount to it depending on available memory.

The stackLimit currently in effect can be fetched using the effective stackLimit.

The recursionLimit property is now bounded by the stackLimit – attempts to set the recursionLimit

30

greater than the stackLimit will see it downwardly adjusted to the maximum current size allowed.

Note: The changes to the recursionLimit property and the new stackLimit property are only implemented on Windows at present.


revBrowser windowId property (4.5.1 – experimental)

There is a long standing issue with revBrowser that causes browser instances to be lost whenever the stack it is attached to has its window re-created. Previously, cases where this would occur had to be avoided when a browser was present on a stack.

To resolve this problem a new property has been added to browser instances – windowId. The windowId property allows the stack to which a browser instance is attached to be changed after it has been created.

If the windowId is set to 0, the browser instance is temporary hidden. If the windowId is set to a valid stack windowId, the browser instance will move to that stack.

For example, to toggle the resizable property of a stack hosting a browser use the following code:

revBrowserSet pBrowserId, "windowId", 0

set the resizable of stack pBrowserStack to pNewResizeableValue

revBrowserSet pBrowserId, "windowId", the windowId of stack pBrowserStack


Improved image export (4.5)

Raw data export (experimental)

It is possible to export raw image data using the following forms:

export target as raw with palette colors

export target as raw with ( standard | optimized ) palette

export target as raw with count color optimized palette

export target as raw [ argb | bgra | abgr | rgab ]

The first three of these operate in the same way as for the other formats as described above except that instead of formatted image data you get the raw palette indices packed appropriately depending on the size of the palette:

<= 2 colors will be 1 bpp



31



The final form allows export of the full 32-bit data of the image with 8 bits per component. In this case, the components are not pre-multiplied with any alpha channel, and appear ordered in memory in increasing bytes.

e.g. The argb form will give you:byte 0 = alpha

byte 1 = red

byte 2 = green

byte 3 = blue

Important: This feature (raw data export) is currently experimental. This means that it may not be complete, or may fail in some circumstances that you would expect it to work. Please do not be afraid to try it out as we need feedback to develop it further.

Elevated process support (4.5 – experimental)

Sometimes it is necessary to perform operations on the local machine as an administrator, and a typical pattern for a GUI application doing this is for it to prompt for authentication at certain points.

Modern operating systems do not permit a process to elevate itself, nor grant itself increased privilege. Instead, they only allow a running process to launch another process with increased privilege. Therefore, in order to support this, a new form of the open process command has been introduced that can launch a slave process with elevated permissions:

open elevated process process [ for [ text | binary ] ( read | write | update | neither ) ]

This form operates identically to the normal version, except that engine will ask the system to launch the given process with admin/root privileges.

The standard way for a GUI application that needs to perform privileged operations to be structured is to split the application into two parts: a GUI front-end that interacts with the user, and a command-line back-end that is run with elevated permissions. These two parts can then talk to each other using a standard master-slave approach, or some other form of IPC such as sockets.


Status icon support (4.5 – experimental)

Windows, Linux and Mac all have an area where so-called 'status icons' can be displayed. On Windows this is the system tray on the bottom right of the start bar, on Linux this is typically the right of the panel at the top of the screen, and on Mac this is on the menubar.

The engine has support for adding a single status icon, and it can be configured using the statusIcon, the statusIconTooltip and the statusIconMenu:

set the statusIcon to imageId

set the statusIconMenu to iconMenuSpec

32

set the statusIconToolTip to toolTip

Here imageId is the id of the image you wish to use as the icon. It will be scaled down automatically to the appropriate size for the platform and then set. The toolTip specifies what message appears when the user hovers over the status icon.

The iconMenuSpec allows you to configure a menu that will appear when the user does a 'menu' click on the icon. This string uses a subset of the standard engine menu specification:

[ <tab> * ] [ '(' ] <label> [ '|' <tag> ]

Here the number of tabs determines the depth of the menu (i.e. use this to create sub-menus). The optional tag is used when calling the statusIconMenuPick message.

Before the engine displays the status icon menu, it will send a statusIconMenuOpening menu to the current card of the defaultStack. You can use this opportunity to change the icon menu before it is displayed, this is an analog to handling mouseDown in a menu button.

When the user selects an item from the dock menu, the engine will send an statusIconMenuPick message to the current card of the default stack:

statusIconMenuPick which

Here which will be a list of labels or tags (if specified) separated by '|' which determines which item was selected.

In addition, the engine will send the following message in response to clicks on the icon:

statusIconClick button

statusIconDoubleClick button

You can use these to perform an appropriate action.

Note: If you wish to display a menu from the status icon you must use the statusIconMenu property, attempting to open a normal popup menu in response to one of the click messages is not guaranteed to work.

Note: This syntax is only implemented on Windows at the moment and replaces the previously unsupported use of the icon and the iconMenu for this purpose. The properties specified above will have no effect on Mac and Linux at this time.


Listing sub-keys in the registry (4.5 – experimental)

To get a list of sub-keys in the Windows registry use the following function:

listRegistry(parentKey)

This will return a return-delimited list of sub-keys, i.e. those keys which are direct children of the given parentKey. The specified key should be in the same format as the other registry functions.


33


HTTPS – automatic root certificate discovery (4.5 – experimental)

In previous versions it was necessary to set the sslCertificates property to the root certificates that HTTPS connections should be verified against. Support has now been added to locate and load the root certificates installed (and kept up to date) as part of the OS.

This uses the standard root certificate keychain on Mac, the standard root certificate store on Windows and uses a number of heuristics to locate this information on Linux.

You can easily find out if the system-installed root certificates are being found by running the following command in the message box:

get url "https://www.google.com"

put the result & return & it

If this results in an error about verification failure then it is likely that root certificates have not been found. Please let us know (particularly on Linux) if you find this simple test fails, making sure you give us full details of your system (e.g. Linux distribution and version).

Note: Unfortunately this feature does not currently work correctly on Mac 10.6.x. For now, we advise including an appropriate root certificates collection with your application, as was previously necessary, and setting the sslCertificates property appropriately.


Mac – dock icon support (4.5 – experimental)

Previously unsupported syntax for manipulating the dock icon on Mac is now experimental.

Choosing an image

The current dock icon image can be set by using the global icon property:

set the icon to imageId

The engine will attempt to find an image with the given id, resize it to 128x128 and then set it as the dock icon for the application.

This property has no effect on other platforms.

Note: The image is only guaranteed to persist while the application runs, although in some cases the OS does appear to cache it beyond this.

Configuring the dock icon menu

In addition to changing the dock icon image, you can also configure the menu that appears when the user clicks on it.

To set the dock icon menu use the global iconMenu property:

set the iconMenu to iconMenuSpec

Here, iconMenuSpec is a string describing the menu. This uses a subset of the standard menu specification syntax. The string should be a return-delimited list of items specified as follows:

34

https://www.google.com/

[ <tab> * ] [ '(' ] <label> [ '|' <tag> ]

Here the number of tabs determines the depth of the menu (i.e. use this to create sub-menus). The optional tag is used when calling the iconMenuPick message.

Before the engine displays the icon menu, it will send a iconMenuOpening menu to the current card of the defaultStack. You can use this opportunity to change the icon menu before it is displayed, this is an analog to handling mouseDown in a menu button.

When the user selects an item from the dock menu, the engine will send an iconMenuPick message to the current card of the default stack:

iconMenuPick which

Here which will be a list of labels or tags (if specified) separated by '|' which determines which item was selected.


Specific bug fixes (5.5.1)

(bug fixes specific to the current build are highlighted in bold, reverted bug fixes are stricken-through)

10276 Unknown fonts renders as symbols on Windows.Drag drop crash if the target object is deleted during drag drop operation.Crash in certain circumstances when drawing graphics with degenerate paths.Crash in certain circumstances when dismissing Linux tooltip.Random chars appear at end of styledText run if returns present.In certain circumstances, sheet file dialogs launched from a stack other than the top stack can cause crash.textShift attribute not imported correctly from htmlText.The mouseColor doesn't return correct values on Mac OS 10.7.Crash on startup when using uniEncode to encode from charset 0 before any others.

10035 Import snapshot doesn't work on Mac OS 10.7.10124 Crash when setting htmlText to malformed input.10130 Crash when setting textFont/Size/Style of image.10132 Setting the clipboarddata[html] causes crash.10134 Setting the rtfText to empty causes crash.10136 Sheet file picker dialog breaks window operations.10141 Memory leak when shared memory off on Linux10144 Crash when copy paste sequence on selected part of image.10157 Card border redrawn incorrectly.10180 WingDings font does not work correctly.10183 Errors with align in tags of HTMLText10185 Crash on closing stack.10193 Certain bitmap images are not imported correctly.10200 Field-level vGrid not drawn from inside border (2 pixels difference from previous versions).10212 Infinite loop when deleting a target field from a 'dragdrop' handler10227 Link style lost when bold style applied inside <a> tag in HTML-text.10258 Answer file with type filters incorrectly for certain filters.

35


Specific bug fixes (5.5)

Hidden attr not saved correctly causing reloading a paragraph's attrs to be corrupted if it is set to true.Undo in fields doesn't trigger textChanged.Pasting text causes caret to appear at correct x but on previous line.The formattedHeight of field gets out of sync if paragraphs with spacing above/below are present.Fonts such as Helvetica Neue display differently depending on whether they've been drawn as Unicode or native on Mac.Crash caused tilecache sprite manipulation when tilecache invalidCrash after accelerated rendering has been switched off.Crash when manipulating closed group with showName true.Crash caused by active field changing in scrollbarDrag handler when pasting into fieldField does not scroll caret in view after pastePadding is not taken into account in selection filling when on top/bottom line of paragraph.In OS 10.5 or earlier, the file dialog crashes in certain situations.The formattedText trims last char of a range.HTML entities between 128 and 160 should be interpreted as Windows-1252 for backwards compatibility.replace command not working correctly when accented characters are present.

2497 Problem setting certain unicode htmlText.2656 When the imageSource of a character is set, the htmlText of the field doesn't accurately

represent the field's contents.2939 Box and 3d-box styles get interrupted at ends of runs in fields3173 Caret and scrollbars don't update correctly when cutting text.3173 Cutting text in a field will not update the formattedWidth correctly.4246 Unclosed style tags in htmlText should be popped when a paragraph terminates.4700 "Italic" undoes "Bold".6369 Set the textfont to empty does not inherit from the object textfont.6484 htmlText returning wrong html if field has textStyle set to bold.7591 Setting htmlText to string with font size and no font inherits rather than assigns.7777 Russian (and other) text input doesn't work in some fields when switching from mac to win8010 Anchor tags incorrectly split into separate tags when it contains an imagesource.9117 Font face lost in Snow Leopard9401 'mixed' textFont incorrectly reported.9430 Whitespace outside of text containing tags is not ignored.9432 GTK theme still renders win-95 style focus border on buttons regardless of theme9511 Win95 focus border drawn on list fields under GTK and hilite color wrong9562 Link style not displayed on entire hungarian word.9590 Heading tag immediately following a list tag is rendered as a list item.9618 Invalid htmlText when combining multiple font colors and bold textStyle.9647 Replace a in b crashes for some values of a and b9659 Javascript calls via revBrowser on OS X cause errors9674 Engine can not get object attributes for UNICODE text9681 HScroll doesn't reset9838 htmlText incorrect for Unicode fields.9895 magnifier window does not render correctly9935 Crash when converting polish dates.

36

9956 Setting / Getting unicode Text CPU intensive9966 Player in background stops when leaving a card9997 Printing a rectangle shows dashes on Windows.10001 Paragraph boxes do not align relative to left, middle or right of visible field.10003 File extension filter does not work in OS X file dialog.10006 Convert command broken under some circumstances.10022 Incorrect handling of null values in an integer SQLite column.10028 Fields with tabstops don't render correctly.10029 The charIndex is always returns one10043 Print card or field causes crash.10044 Import snapshot from stack which is not open fails.10045 "The target" in group script references the group itself.10046 “New Folder” button missing from OS X file dialog.10053 Change field label in edit mode causes crash.10059 Numbered list numbers are not correct color when hilited.10063 Clickloc reports incorrect location.10069 Table objects do not display correctly.10069 Fields with vGrid set display incorrectly.10074 Group's graphic not receiving mouseDown message.10074 mouseDown sent to card if group hidden in mouseDown handler.10078 Crash on opening standalone application settings.10081 Double in htmlText is broken.10082 Putting images into fields causes crash.10083 Labels of buttons display as Asian characters.10094 The charIndex fails always returns the index of the first word in a line.10117 Crash when htmlText has unrecognized tag present.10118 Crash caused by setting the flaggedRanges.

37


IDE Changes

Updates for new unicode and textStyle functionality (5.5 DP2)

Property Inspector

The property inspector has been updated to use the new unicodeText and unicodeLabel properties. This allows for the direct setting of unicode labels, field content and button text from directly within the inspector.

Menu Builder

The Menu Build has been updated to use unicodeText property.

Menu - Edit > Text

The edit > text menu has been updated to manipulate the styledText property of the object. Properties set by the edit menu include textStyle, textSize, textAlign, textFont and textColor.

Getting folder locations within the IDE

If you write plugins, or have code that relies on the location of IDE files then please ensure you use the following access functions to locate them:

revEnvironmentToolsPath() The location containing the main IDE files.revEnvironmentToolsetPath() The location of the main IDE stacks.revEnvironmentExternalsPath() The location of the externals that come with the IDE.revEnvironmentPluginsPath() The location of the plugins that come with the IDE.revEnvironmentRuntimePath() The location of the standalones that come with the IDE.revEnvironmentDocumentationPath() The location of the documentation files.revEnvironmentResourcesPath() The location of the resources that come with the IDE.revEnvironmentCustomizationPath() The location of the IDE customization folder.revEnvironmentUserCachePath() The location of the folder to use for caching files.revEnvironmentUserPreferencesPath() The location of the folder to use for preference files.revEnvironmentUserExternalsPath() The location of the folder to use for additional externals.revEnvironmentUserPluginsPath() The location of the folder to use for additional plugins.revEnvironmentUserResourcesPath() The location of the folder to use for additional resources.

Important: Third-party IDE extensions must avoid placing any files inside the application bundle or under revEnvironmentToolsPath() (not least because you will probably not have privileges to do so!). Instead, they should use the user-externals and user-plugins paths as provided. These paths are determined by the user's customization path setting, configurable in the preferences.

Standalone builder

Windows – UAC Manifest

It is now possible to specify what action UAC should take on Windows Vista and higher when the

38


standalone is launched. You can choose one of the following options:

Default No UAC option is provided in the manifest.Save as Invoker The application will run with the same privileges as the process that

invoked it.Highest available The application will be elevated to the highest privilege level the current

user is allowed.Require administrator The application will be run as administrator after prompting the user for

appropriate login/elevation rights.

Web

Using the 5.5 standalone builder to build for Web will create revlets. These are compatible with the existing revWeb plug-in available from revweb.runrev.com.

An updated version of the IDE for producing LiveCode Applets and the associated LiveCode player will be made available in due course.

Note: As the currently available revWeb plug-in uses the 4.0 engine, you must be careful to only use features that are present in that version.

Datagrid

The datagrid is currently at version 1.0.2 (build 14).

1.0.2 (build 12) Added specific scrollbar width for linux platform.

DeleteFieldEditorAndOpenNext now continues looking for a column to edit if EditValue is passed in the behavior script. This allows the developer to skip a column for editing. Previously this would only occur if EditValue was not handled.

DeleteFieldEditorAndOpenNext now skips invisible columns.

The control that DeleteFieldEditorAndOpenNext was targeting would sometimes be changed behind the scenes. This would cause CloseFieldEditor to be sent to the wrong control.

1.0.2 (build 13) ResetList code is now in dgResetList. This allows the developer to intercept

ResetList and manually call dgResetList while adding their own logic.

1.0.2 (build 14) SortDataByKey specifically uses the first line of data in the column. Previously if there were multiple lines in a value it would cause problems.

Fixed some issues in the auto scroll code used in drag/drop operations.

When setting the "scrollbar width" property the new value was not being passed into the function that sets the scrollbar width (bug 9684).

1.0.2 (build 15) Scrollbar width now reads correctly from registry.

Fixed bug with setting the dgText of a datagrid on another card (9575).

Fixed bug in datagrid setup (9576).

39


Specific bug fixes (5.5.1)

(bug fixes specific to the current build are highlighted in bold, reverted bug fixes are stricken-through)

10027 After drawing a polygon objects can no longer be selected.Preferences being saved in 5.5 format in some cases.Fixed issue with converting old Revolution prefs to new LiveCode prefs.

Specific bug fixes (5.5)

Deployed Revlets no longer work.9752 Documentation view preference not changing.9919 Controls in standalone builder stay disabled9998 Dashes in environment variables causes errors.10058 Property inspector fails to open.10072 'Revolution' still mentioned in pref stack.10073 New stack file format prevents prefs stack from being backwards compatible.10075 Setting text color to 'pen color' in edit menu doesn't work.

User Guide

No changes.

Dictionary

Dictionary entries have been created and updated for the appropriate new and updated features.

Mobile Examples

No changes.

40


Previous Release Notes4.5.0 Release Notes http://www.runrev.com/downloads/livecode/4_5_0/LiveCodeNotes-4_5_0.pdf

4.5.1 Release Notes http://www.runrev.com/downloads/livecode/4_5_1/LiveCodeNotes-4_5_1.pdf





4.6.2 Release Notes http://www.runrev.com/downloads/livecode/4_6_2/LiveCodeN otes-4_6_2.pdf

4.6.3 Release Notes http://www.runrev.com/downloads/livecode/4_6_3/LiveCodeNotes-4 _6_3.pdf


5.0.0 Release Notes http://www.runrev.com/downloads/livecode/5_0_0/LiveCodeNotes-5_0_0.pd f



RevisionsRevision 1 MM Document created for 5.5-dp-1Revision 2 MM Updated engine bug fix list for 5.5-dp-2.

Updated IDE bug fix list for 5.5-dp-2.Updated Datagrid for 1.0.2 build 15.Added section “Updates for new unicode and textStyle functionality”.Added section “Unlinking of text properties in objects”.Added section “Manipulating unicode in objects”.

Revision 3 MM Updated engine bug fix list for 5.5-dp-3.Updated IDE bug fix list for 5.5-dp-3.Added section “Paragraph hiding”.Added section “Updated htmlText”.Added section “Updated rtfText”.

Revision 4 MM Updated engine bug fix list for 5.5-rc-1.Updated IDE bug fix list for 5.5-rc-1.Added section “The unicodeToolTop property”.Updated section “Updated rtfText”.

Revision 5 MM Updated engine bug fix list for 5.5-rc-2.Revision 6 MM Updated engine bug fix list for 5.5-gm-1.Revision 7 MM Updated engine bug fix list for 5.5-gm-2.

Updated IDE bug fix list for 5.5-gm-2.Revision 8 MM No changes.Revision 9 MM Updated engine bug fix list for 5.5.1-dp-1.Revision 10 MM Updated IDE bug fix list for 5.5.1-dp-2.

Updated engine bug fix list for 5.5.1-dp-2.Revision 11 MM Updated IDE bug fix list for 5.5.1-rc-1.

41

http://www.runrev.com/downloads/livecode/5_0_2/LiveCodeNotes-5_0_2.pdf



http://www.runrev.com/downloads/livecode/5_0_0/LiveCodeNotes-5_0_0.pd



http://www.runrev.com/downloads/livecode/4_6_3/LiveCodeNotes-4


http://www.runrev.com/downloads/livecode/4_6_2/LiveCodeN








Updated engine bug fix list for 5.5.1-rc-1.Revision 12 MM Updated IDE bug fix list for 5.5.1-rc-2.

Updated engine bug fix list for 5.5.1-rc-2.Revision 13 MM Updated engine bug fix list for 5.5.1-rc-3.Revision 14 MM Updated engine bug fix list for 5.5.1-rc-4.Revision 15 MM Updated engine bug fix list for 5.5.1-gm-1.

Updated IDE bug fix list for 5.5.1-gm-1.

42

livecode 5.5.1 release notes€¦ · livecode 5.5.1 is an update to 5.5, introducing mobile...

Documents