[ Impressum ]

LiveCode BasicLib

www.Rozek.de > LiveCode > BasicLib
The "BasicLib" is a small LiveCode [1] "Library Stack" with a few simple, yet commonly used functions.

Download and Installation

The "BasicLib" is available as an unencrypted LiveCode stack and can be downloaded from here:
After downloading, just place the "BasicLib" in a directory of your choice - an explicit installation is not required.

Usage Instructions

The "BasicLib" has been implemented as a LiveCode "library stack" and must therefore be attached to a "MainStack" prior to its use using

start using stack "BasicLib"

Appropriately, this statement is executed in the context of a preOpenStack procedure of a MainStack.

Should the MainStack later be converted into a standalone application, the "BasicLib" must also become part of the list of "Stack Files" in this MainStack (this is easiest done by using the "Standalone Application Settings" from the LiveCode development environment).

Usage Instructions for mobile Applications

The "BasicLib" can also be used in mobile applications. However - and unlike for standalone desktop applications - it must then be included in the list of "non-stack files" and attached to the MainStack using

start using stack (specialFolderPath("engine") & "/BasicLib.livecode")

The list of "non-stack files" can likewise be found on the "Copy Files" page in the "Standalone Application Settings" of the LiveCode development environment.

Function Overview

The "BasicLib" contains only functions, no commands.

String Utilities

A set of functions is dealing with the contents of strings. These are (in alphabetical order):

enquoted (<Candidate>)


enquoted returns a copy of the string Candidate, in which all single quotes (') have been replaced by double ones (").

Since LiveCode does not know any escape sequences (such as \"), the insertion of double quotes into a string literal might become somewhat tedious:

put "say" && quote & "Hello!" & quote && "to me" into myMessage

The merge function does not really help in this situation:

put "say [quote]Hello![quote] to me" into myMessage

But as long as the string does not need to contain any single quotes, enquoted turns out to be quite helpful:

put enquoted("say 'Hello!' to me") into myMessage

HTMLSafe (<Candidate>)


HTMLSafe returns a copy of the string Candidate in a format which can be safely displayed in a web browser. For this purpose, the characters <,> and & are replaced by their HTML equivalents.

printable (<Candidate>)


printable returns a copy of the string Candidate in a format which can be safely displayed. For this purpose, all control characters are replaced by their corresponding escape sequences such as \n, \r or \x04.

quoted (<Candidate>)


quoted returns a copy of the string Candidate enclosed in double quotes (").

quotedPrintable (<Candidate>)


quotedPrintable returns a copy of the string Candidate in a safely displayable format and enclosed in double quotes (").

trimmed (<Candidate>)


trimmed returns a copy of the string Candidate without any leading or trailing blanks.

Unicode Support

The use of Unicode in LiveCode applications is still quite tedious. The following functions shall simplify this a bit (in alphabetical order):

ISOtoUnicode (<ISOtext>)


ISOtoUnicode returns a copy of the ISO 8859-1 encoded string ISOtext in Unicode format.

On non-Mac OS systems, this behavior corresponds to the function uniEncode - under Mac OS X, however, uniEncode does not work correctly, which is why ISOtoUnicode should be used instead.

putUnicodeAfterMsg (<UnicodeText>)


putUnicodeAfterMsg appends the Unicode string UnicodeText to the contents of the Message Box.

putUnicodeIntoMsg (<UnicodeText>)


putUnicodeIntoMsg clears the contents of the Message Box and inserts the Unicode string UnicodeText instead.

UnicodeToISO (<UnicodeText>)


UnicodeToISO returns a copy of the Unicode-encoded string UnicodeText in ISO 8859-1 format. This is achieved by simply ignoring the most significant byte of each character - therefore, characters outside the range 0...255 may probably lead to undesirable results.

On non-Mac OS systems, this behavior corresponds to the function uniDecode - under Mac OS X, however, uniDecode does not work correctly, which is why UnicodeToISO should be used instead.

Creating References

Sometimes you need a reference to the surrounding group, card or stack containing the control with the currently running script. The following functions enable the creation of such references in a general manner (in alphabetical order):

CardOf (<ControlRef>)


CardOf returns a reference to the card containing the control referenced by ControlRef.

currentCardOf (<ControlRef>)


currentCardOf returns a reference to the currently active card of the stack containing the control referenced by ControlRef.

MainStackOf (<ControlRef>)


MainStackOf returns a reference to the MainStack of the stack containing the control referenced by ControlRef.

myCard ()


myCard returns a reference to the card containing the control with the script from which myCard was called.

myCurrentCard ()


myCurrentCard returns a reference to the currently active card of the stack containing the control with the script from which myMainStack was called.

myMainStack ()


myMainStack returns a reference to the MainStack of the stack containing the control with the script from which myMainStack was called.

myOwner ()


myOwner returns a reference to the next outer group or card or the next outer stack containing the control with the script from which myOwner was called.

myStack ()


myStack returns a reference to the stack containing the control with the script from which myStack was called.

OwnerOf (<ControlRef>)


OwnerOf returns a reference to the next outer group or card or the next outer stack containing the control referenced by ControlRef.

StackOf (<ControlRef>)


StackOf returns a reference to the stack containing the control referenced by ControlRef.

Miscellaneous

The following function does not fit into any of the categories mentioned above:

iif (<Condition>, <TrueValue>, <FalseValue>)


If the Condition argument is true, iif returns the value of the TrueValue argument - otherwise the one of the FalseValue argument.

In this way you can probably save writing a complete if-then-else statement - under the condition that the TrueValue and FalseValue arguments may always be evaluated when iif is called (and this evaluation does not require too much computational effort).

A typical (although constructed) example would be the use of

return iif(myValue is not empty, myValue, myDefault)

instead of

if (myValue is empty) then
return myValue
else
return myDefault
end if

System Requirements

The "BasicLib" requires LiveCode 6.x or later, and works regardless of the operating system on both stationary and mobile platforms.

Dependencies

The "BasicLib" does not depend on any other stack.

Automated Tests

There is also a separate stack with (an incomplete set of) automated tests of the "BasicLib":
When this stack is opened, the command performTests is executed, which is responsible for running the actual tests. In the end, the "Message Box" of the LiveCode development environment should appear and display the message

all tests passed

Otherwise, an error message with information about the failed test should be shown instead.

Known Bugs

There are currently no known bugs in the "BasicLib".

License Information

The "BasicLib" and its tests are licensed under a "Creative Commons Attribution 4.0 Unported license", which essentially means that you may both use and modify them (even in a commercial context) - provided that your changes have been marked as such and there is a reference to me as the original author at an appropriate place.

                       
Have fun with LiveCode and the "BasicLib"! Creative Commons License

Bibliography

[1]
(RunRev Ltd.)
LiveCode | Create apps for multiple platforms. Quickly. Easily. Free
LiveCode is a development environment for both stationary (Windows, Linux, MacOS X) and mobile (iOS, Android) applications modeled after the legendary Apple HyperCard. A visual editor allows fast design of user interfaces, a programming language inspired by the english language allows even non-professional programmers to develop professional applications and the concept of "modifying a running program" simplifies testing and troubleshooting.