Main

Guida A Livecode

Main.GuidaALivecode History

Hide minor edits - Show changes to output

Added lines 26-30:
!!Aggiornamenti
Visto che questa e' una guida generale se volete avere più informazioni vi consiglio di seguire il mio blog:
(:html:)
<script src="http://feeds.feedburner.com/LivecodeItalia?format=sigpro&dateFormat=d/M/yyyy" type="text/javascript" ></script><noscript><p>Subscribe to RSS headline updates from: <a href="http://feeds.feedburner.com/LivecodeItalia"></a><br/>Powered by FeedBurner</p> </noscript>
(:htmlend:)
August 22, 2016, at 04:19 PM by 79.58.39.104 -
Added lines 80-81:

Ho fatto anche dei pacchetti di installazione scaricabili da qui: http://www.maxvessi.net/livecode/linux/index.php
Changed lines 95-98 from:
Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial" che costa $ 500 anno.  Dopo aver immesso la chiave della licenza del programma, Livecode diventera' COMMERCIAL per un anno, poi tornera' COMMUNITY. Questo non vuol dire che i vostri programmi durino solo un anno, i vostri programmi creati con Livecode COMMERCIAL saranno sempre closed source. Il termine della licenza influenza solo l'ambiente di sviluppo per creare nuovi programmi o nuove versioni del programma.

Per le aziende e infrastrutture molto grandi, che hanno bisogno di supporto telefonico, corsi specifici e soluzioni in 24 ore e' possibile acquistare licenze annuali dai costi piu' alti che garantiscono del personale dedicato per 12 mesi.
to:
Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial.  Dopo aver immesso la chiave della licenza del programma, Livecode diventera' COMMERCIAL, scaduta la licenza Livecode poi tornera' COMMUNITY. Questo non vuol dire che i vostri programmi durino solo un anno o meno, i vostri programmi creati con Livecode COMMERCIAL saranno sempre closed source. Il termine della licenza influenza solo l'ambiente di sviluppo per creare nuovi programmi o nuove versioni del programma.

Per le aziende e infrastrutture molto grandi, che hanno bisogno di supporto telefonico, corsi specifici e soluzioni in 24 ore e' possibile acquistare licenze dai costi piu' alti che garantiscono del personale dedicato per 12 mesi.
Changed lines 100-101 from:
Ecco un elenco aggiornato delle Licenze (Luglio 2014):
to:
Ecco un elenco aggiornato delle Licenze (Settembre 2015):
Changed lines 103-109 from:
* '''Membership''': costa $ 99 all'anno, permette di ottenere programmi non commerciali per Windows, Linux, Mac, Android e iOS. Il codice rimane aperto.
*  '''Indy''': costa $ 299 all'anno, permette di ottenere programmi commerciali per Windows, Linux, Mac, Android e iOS. Il codice può essere chiuso.
*   
'''Business''': costa $ 999. E' obbligatoria se si guadagna più di $ 500'000 all'anno con Livecode (Si, c'è gente che guadagna così tanto programmando con Livecode). Vi da accesso ad un forum riservato.
*    '''Pro''': costa $ 1'999 all'anno. Vi assegnano un account manager personale, vi telefonano direttamente per capire cosa volete fare con Livecode, i bug segnalati da voi vengono risolti prima, avete delle anteprime sugli sviluppi di Livecode.
*    '''Premium''': costa $ 10'000 l'anno, oltre tutti i benefici della Pro, avete: funzioni aggiuntive richieste da voi hanno la precedenza, supporto telefonico, tutti i pacchetti aggiuntivi sono inclusi, biglietto per il congresso annuale incluso, una vostra app viene testata e migliorata direttamente dai programmatori di Livecode.


to:
*  '''Indy''': costa € 55 al mese, permette di ottenere programmi commerciali per Windows, Linux, Mac, Android e iOS. Il codice può essere chiuso.
  '''Business''': costa $ 188 al mese. E' obbligatoria se si guadagna più di $ 500'000 all'anno con Livecode (Si, c'è gente che guadagna così tanto programmando con Livecode). Vi da' accesso ad un forum riservato.

L'elenco delle licenze e qui: https://livecode
.com/products/livecode-platform/pricing/
Changed lines 109-110 from:
C'e' il forum: http://forums.livecode.com , li' troverete molti esperti.
to:
Added lines 112-113:
C'e' il forum in inglese: http://forums.livecode.com , li' troverete molti esperti.
Deleted line 2084:
March 17, 2015, at 02:12 PM by 79.58.39.104 -
Added line 2065:
*lettura testi, (''text to speech'')
August 06, 2014, at 01:40 PM by Massimiliano Vessi -
Changed lines 2069-2084 from:
to:
(:html:)
    <div id="disqus_thread"></div>
    <script type="text/javascript">
        /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
        var disqus_shortname = 'wwwmaxvessinet'; // required: replace example with your forum shortname

        /* * * DON'T EDIT BELOW THIS LINE * * */
        (function() {
            var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
            dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
            (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
        })();
    </script>
    <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
    <a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
    (:htmlend:)
July 09, 2014, at 05:14 PM by Massimiliano Vessi -
Added line 32:
*http://livecodeitalia.freeforums.org/
Deleted lines 114-115:
C'è il forum italiano: https://groups.google.com/forum/#!forum/livecode-italia
Changed line 275 from:
Poi ci sono tutta una serie di link per svariati aiuti, dalla newsletter alla forum.
to:
Poi ci sono tutta una serie di link per svariati aiuti, dalla newsletter al forum.
July 09, 2014, at 05:13 PM by Massimiliano Vessi -
Added lines 111-112:

C'e' il forum italiano: http://livecodeitalia.freeforums.org/
July 09, 2014, at 05:11 PM by Massimiliano Vessi -
Changed lines 98-99 from:
!! Elenco licenze (Luuglio 2014)
Ecco
un elenco aggiornato delle Licenze:
to:
!! Elenco licenze
Ecco un elenco aggiornato delle Licenze (Luglio 2014):
July 09, 2014, at 05:11 PM by Massimiliano Vessi -
Added lines 97-107:

!! Elenco licenze (Luuglio 2014)
Ecco un elenco aggiornato delle Licenze:

* '''Community''': è gratuita permette di ottenere programmi con licenza GPL per Windows, Linux, Mac e Android. (iOS non permette programmi pienamente GPL)
* '''Membership''': costa $ 99 all'anno, permette di ottenere programmi non commerciali per Windows, Linux, Mac, Android e iOS. Il codice rimane aperto.
*  '''Indy''': costa $ 299 all'anno, permette di ottenere programmi commerciali per Windows, Linux, Mac, Android e iOS. Il codice può essere chiuso.
*    '''Business''': costa $ 999. E' obbligatoria se si guadagna più di $ 500'000 all'anno con Livecode (Si, c'è gente che guadagna così tanto programmando con Livecode). Vi da accesso ad un forum riservato.
*    '''Pro''': costa $ 1'999 all'anno. Vi assegnano un account manager personale, vi telefonano direttamente per capire cosa volete fare con Livecode, i bug segnalati da voi vengono risolti prima, avete delle anteprime sugli sviluppi di Livecode.
*    '''Premium''': costa $ 10'000 l'anno, oltre tutti i benefici della Pro, avete: funzioni aggiuntive richieste da voi hanno la precedenza, supporto telefonico, tutti i pacchetti aggiuntivi sono inclusi, biglietto per il congresso annuale incluso, una vostra app viene testata e migliorata direttamente dai programmatori di Livecode.

July 07, 2014, at 05:55 PM by Massimiliano Vessi -
Changed line 35 from:
*http://forums.runrev.com  forum
to:
*http://forums.livecode.com  forum
June 04, 2014, at 10:17 AM by Massimiliano Vessi -
Changed line 99 from:
C'e' il forum: http://forums.runrev.com , li' troverete molti esperti.
to:
C'e' il forum: http://forums.livecode.com , li' troverete molti esperti.
May 08, 2014, at 05:48 PM by Massimiliano Vessi -
Added lines 101-102:
C'è il forum italiano: https://groups.google.com/forum/#!forum/livecode-italia
Changed lines 107-111 from:
to:
C'e' il blog italiano: http://livecodeitalia.blogspot.it/



Changed lines 1549-1555 from:
to:
!!Spostare gli oggetti col mouse (drag)

Per attivare la funzione che permetta ad un oggetto di essere spostato o trascinato, basta aggiungere all'oggetto il seguente codice:

 on mouseDown
  grab me
 end mouseDown
May 02, 2014, at 10:50 AM by Massimiliano Vessi -
Added line 31:
* http://livecodeitalia.blogspot.it/
February 28, 2014, at 03:54 PM by Massimiliano Vessi -
Changed lines 2019-2051 from:
13.5Working with Visual Transition Effects

LiveCode supports visual transition effects when changing card or hiding and showing
objects. There are three types of effect support: built-in effects which work on allplatforms, QuickTime effects which work on systems that have QuickTime installed and
Core Image effects which work on Mac OS 10.4 or later.

Use the visual effect command to display a visual effect. To go to the next card
with a dissolve transition effect:

visual effect dissolve slow
go next card

To make changes to objects on the screen with a visual effect (e.g. hide, show or movethem), first lock the screen, then make the changes, then unlock the screen:

lock screen
hide image 1show image 3unlock screen with visual effect "wipe right"

To choose a QuickTime effect using the effect chooser dialog use:

answer effect
-- store the visual effect as a custom propertyset the cEffect of this stack to it

Then:

 
visual effect (the cEffect of this stack)
go next card

For more information on visual effects, see the visual effect command in the
LiveCode Dictionary. To try out the different visual effects available in an interactive
format see the Multimedia Workshop, available at:

http://www.runrev.com/developers/exploring-LiveCode/multimedia/
to:


!Schermo intero

Per mettere un'applicazione a schermo intero, basta impostare la proprieta' '''fullScreen''':

 set the fullScreen of this stack to true

February 28, 2014, at 03:52 PM by Massimiliano Vessi -
Changed lines 2053-2072 from:
13.6Creating Custom Skins

In addition to its support for system native controls, LiveCode allows you
the ability to
create an entirely custom look, or skin, for your application. All of the built-in elementscan be replaced with themed graphics allowing you to create rich multimedia. For
example, LiveCode buttons support "icons" of unlimited size which can be used to
replace the native appearance of a button entirely. Windows can be irregularly shaped
and even contain holes and alpha mask (variable) transparency. All of LiveCode's objectssupport a variety of transfer modes or inks. Stacks can take over the entire screen or bedisplayed with a backdrop.

13.6.1 Custom Themed Buttons
To create a custom button, first create a regular button. Open the Inspector for the button
and set its style to Transparent. Turn off the Show Name property. Next, switch to the
Icons & Border pane in the Inspector. Turn off the Hilite Border property. You can nowselect any image you have imported to use as an icon for the button. To set the mousedown state, set the hilite icon. To set the roll over state set the hover icon.

Important: A button "icon" may be an image of any size in LiveCode, allowing acompletely custom look.
Tip: To use the same set of images as icons throughout your stack file, create a substack
and import all your theme images into it. Set the ID property of each image to a high
value (between 10,000 and 100,000) so that it will be unique. You can now reference that
image anywhere in your application. If you want to change theme, you only need to
replace that image with another image and give it the same ID.
Tip: Any object in LiveCode can behave like a button. For example, if you want tocreate a graphic that responds when a user clicks on it, create the graphic and add amouseUp handler to it, in the same way you would with a button.
to:
!Schermo intero

Per mettere un'applicazione a schermo intero, basta impostare la proprieta' '''fullScreen''':

 set
the fullScreen of this stack to true

Deleted lines 2060-2177:
13.6.2 Irregular Windows
To create an irregularly shaped window, import or create an image that has atransparency mask. Then use the Stack Inspector to choose that image as the stack's
Shape. To change the shape by script, set the windowShape property. Many modern
window managers support alpha blended windows (variable degrees of transparency). To
create a window with an alpha channel, import a PNG that contains an alpha channel and
set the windowShape to this image.

13.6.3 Blend Modes (transfer modes or inks)
Blend modes determine how an object's colors combine with the colors of the pixelsunderneath the object to determine how the object's color is displayed. To set the blend
mode of an object, use the Blending pane in the Inspector or set the object's ink
property. All objects in LiveCode support blend modes, with the exception of stacks.

set the ink of image "picture" to "blendBurn"

For more information, see the ink entry in the LiveCode Dictionary.

To set the degree of transparency, set the object's blendLevel property. All LiveCode
objects (including stacks) support blendLevel:

set the blendLevel of button 1 to 50 -- sets a button to
50% transparent

13.6.4 Full screen mode
A stack can be displayed as full screen by setting its fullScreen property to true:

set the fullScreen of this stack to true

Set this property back to false to exit full screen mode.

If you want to hide or show the menu bar on Mac OS X use the hide menubaror
show menubar commands:

hide menuBar
show menuBar

Similarly, use hide taskbar and show taskbar on Windows systems to hide and
show the taskbar.

13.6.5 Displaying a Backdrop
To display a backdrop set the backDrop global property. You may set the backDropto a solid color or to the ID of an image.

set the backDrop to "black"

 
To remove the backDrop:
set the backDrop to none

376


 
Appendix A: Shortcuts Reference


Windows / Linux Mac OS X
The Development EnvironmentChoose run (browse) tool Control-9 Command-9
Choose edit (pointer) tool Conttrol-0 Command-0
Toogle between run and edit tools Control-alt-tab Command-option-tab
Hide or show palettes Control-tab Command-control-tab
Display context menus when running Control-shift-right Command-controlclick
shift-click
Save all open stacks Control-alt-s Command-option-s
Apply default button in Save dialog Return Return
Apply non-default button in save dialog Control-1st letter of Command-1st letter of
button button
NavigationGo to the first card Control-1 Command-1
Go to the previous card Control-2 Command-2
Go to the next card Control-3 Command-3
Go to the last card Control-4 Command-4
Go to the recent card Control-5 Command-5
Go to the top or bottom of a field Control-up/down Command-up/down
arrow arrow
ObjectsSelect all Control-a Command-a
Duplicate Control-d Command-d
Create card Control-n Command-n
Nudge control Arrow keys Arrow keys
Nudge control by 10 pixels Shift-arrow-keys Shift-arrow-keys
Open object inspector for selection Return Return
Open stack inspector Control-K Command-K
Remove styles from selected text Control-; Command-;
Equalize heights of selected controls Control-shift-= Command-shift-=
Equalize width of selected controls Control-= Command-=
Magnify image with paint tool Control-right-click Command-click
Apply transparency with paint tool Control-click Control-click
Constrain paint tool selection to a Shift Shift
square
Constrain object aspect ratio Shift Shift
The Code Editor
Edit script of selected object Control-e Command-e
Edit card script Control-shift-c Command-shift-c

 
Edit stack script stack script Control-shift-s Command-shift-s
Edit script of object under mouse Control-alt-click Command-option-click
Apply changes Enter Enter
Apply changes and close Enter twice Enter twice
Apply changes and save stack Control-s Command-s
Comment out selected lines Control-hyphen Command-hyphen
Remove comments Control-shift-hyphen Command-shift-hyphen
Switch to find mode Control-f Command-f
Find next Control-g Command-gFind selected text Control-Option-f Command-Option-f
Format current handler Tab Tab
The Message BoxOpen/close message box Control-m Command-m
Switch to first tab in message box Control-m Command-m
Clear message field Control-u Command-u
Scroll through recent messages (single Up/down arrow Up/down arrow
line)
Scroll through recent messagesAlt-up/down arrow Option-up/down arrow
(multiple line)
Execute message (single line) Return Return
Execute message (multiple line) Enter Enter
Control-Return Control-Return
The DebuggerStep Into F11 F11
Step Over F10 F10
Step Out Shift-F11 Shift-F11
Run F5 F5
Stop Shift-F5 Shift-F5
Abort Control-. Command-.
February 28, 2014, at 03:47 PM by Massimiliano Vessi -
Changed lines 1986-2143 from:
13.2Working with Vector Graphics

In addition to bitmap graphics, LiveCode also supports vector graphics. You can createvector graphics using the graphics tools, or by script. You can manipulate theminteractively in the IDE or by script. You can relayer them, export a description of themor convert them to bitmap format.

Tip: Animation Engine is a 3rd party library that includes a set of functions for
programming interactive graphic animations. See the Related Software section of our
web site for more information.
13.2.1 The Vector Graphic Tools
To see the graphic tools, unfold the triangle at the bottom right of the tools palette. Thegraphics tools are located above the paint tools on the tools palette. The graphic toolsoperate in the same way as the paint tools, except that each time you draw a shape a newgraphic object is created. Unlike paint graphics, you can resize and adjust graphic objectsafter you have created them. For more information on the individual shapes, see thesection on Paint Tools, above.

13.2.2 Creating Graphics by Script
To create graphics by script, set properties of the templateGraphic then use the
create graphic command. For more information on template objects, see the
section Creating objects off screen using the template objects in Chapter 7.

13.2.3 Manipulating graphics by script
Because each graphic is an individual object, you manipulate its appearance by setting
properties rather than using the drag commands (as with the paint tools, above). You can
control all properties of the graphic object by script including the rectangle, line and fillproperties. You can change a graphic from one type to another (e.g. a rectangle to an
oval) by setting its style property.

 
The polygon style of graphic has a points property which allows you to set the
individual points of a line.

Simple motion can be applied using the move command. For example, to move a graphic
100 pixels to the right asynchronously:

move graphic 1 relative 100,0 without waiting

For more information, see the move command in the LiveCode Dictionary.

To program a more complex animation effect, calculate the changes to the points or
rectangles and set these values using timer based messaging. The following examplescales a graphic named "rectangle" down by 100 pixels over the course of 1 second.

local sCount

on mouseUp

 put 0 into sCount

 scaleGraphicend mouseUp

on scaleGraphic

 add 1 to sCount

 if sCount > 100 then exit scaleGraphic

get the rect of graphic "rectangle"

add 1 to item 1 of it

 add 1 to item 2 of it

 subtract 1 from item 3 of it

 subtract 1 from item 4 of it

 set the rect of graphic "rectangle" to it

send "scaleGraphic" to me in 10 millisecondsend scaleGraphic

See the section on Timer based messaging for more information on using timers.

13.3Working with Video

LiveCode supports playback of video with the player object. On Windows and Mac OS,
QuickTime is supported. QuickTime allows playback of a wide variety of file formats,
including MPEG, H.264 and AAC. LiveCode also supports the controller, accessing
QuickTime's streaming features and QuickTime Virtual Reality (QTVR).

On Windows systems, the player object can play back video using the Windows Media
subsystem. This has more limited functionality than using QuickTime.

On Linux Systems, the player object can play back video using mplayer. There are some
functionality limitations: alwaysBuffer, the startTime, endTime and

 
playSelectionproperties have no effect, showController has no effect and play
step forward/play step back do not work reliably.

In addition to these features, LiveCode has built-in support for the animated GIF format.
Animated GIF files can be played back without 3rd party software. See above for moreinformation. Other formats supported by plug-ins in web browsers can be played back
using revBrowser (e.g. Flash). See the topic on revBrowser for more information.

13.3.1 The Player Object
Use the player object to play and interact with video and audio. To create a player object,
drag one onto your stack from the Tools palette. To select a movie file to play, open theInspector for the player object and select a file to use as the source. Doing this sets theplayer's fileName property.

To stream a movie from an Internet server, set the fileName property to the URL addressof the stream.

To play a player, use the start and stop commands.

start player 1stop player 1

The following table describes commonly used player properties:

Property Name Function Example
alwaysBuffer Forces the player to set the alwaysBuffer ofbe buffered, allowing player 1 to true
objects to be drawn
on top and the currentframe to be printed
showController Shows or hides the set the showController
QuickTime controller of player 1 to falsecurrentTime Sets the current frame set the currentTime of
player 1 to 1000duration & The duration of the put (the duration oftimeScale movie and the me/the timeScale of me)
number of intervals into tRunTime
per second of a movie
currentTimeChanged Message sent when on currentTimeChangedthe current frame pIntervalchanges put pInterval intofield "Time Code"
end currentTimeChangedstartTime The start time of the set the startTime of
selection player 1 to 500endTime The end time of the set the endTime of

 
selection player 1 to 1000showSelection Show the selection in set the showSelection of
the controller player 1 to trueplaySelection Play only theset the playSelection ofselection player 1 to trueplayRate The speed to play theset the playRate ofmovie. Set this to -1 player 1 to 2to play backwards
looping Causes playback to set the looping ofloop player 1 to trueplayLoudness Set the volume set the playLoudNess ofplayer 1 to 50tracks List of tracks within put the tracks of playerthe movie 1 into tTracksList
enabledTracks Enable or disable Set the enabledTracks of
tracks player 1 to 3callbacks A list of messages to set the callbacks of
be sent when the player 1 to "1000,
movie reaches nextScene"
specified time points

The following properties can be used to control a QTVR movie: pan, tilt, zoom,
currentNode, nodeChanged, hotspots, and hotSpotClicked.

For more information on any of these terms, see the LiveCode Dictionary.

13.3.2 Preventing Use of QuickTime on Windows
To force LiveCode to use the Windows Media subsystem instead of QuickTime on
Windows systems, even when QuickTime is installed, set the dontUseQT global
property to true.

Important: You must set dontUseQT to true before you perform any movie or player
related action.
13.4Working with Sounds

In addition to playing back sound in a wide variety of formats using the player object,
LiveCode has in-built support for playback of WAV, AIFF and AU format audio clips.

Note: We recommend you use the player object for playing audio as it supports a widerange of formats and compression types. Use the audio clip when you need basic audio
playback on systems that do not have any of the 3rd party libraries supported by the
player object installed.
 
13.4.1 Importing an Audio Clip
To import an audioClip choose File -> Import as Control -> Audio File. This will importthe selected audio file into the current stack as an audioClip.

13.4.2 Playing an Audio Clip
To play an audio clip:

play audioClip 1

To stop playing

play stop

To set the volume:

-- sets the volume to 50%
set the playLoudness of audioclip 1 to 50
to:
!Lavorare con Video e Audio

Per i video Livecode si appoggia a:

* QuickTime, su Windows e Mac
* Mplayer su Linux

in questo modo potete sfruttare ogni tipo di file riconosciuto da questi lettori (MP£, MP4, AVI, ...). Per sfruttare questa capacità basta creare un lettore, e' l'icona vicino a quella delle immagini nella ''Tool Palette''', in questo modo vi ritroverete un ''player''; oppure da codice:

 create player "esempio"
 set the filename of player "esempio" to "miofile.avi"
 set the currentTime of player "esempio" to zero
 start player "esempio"

per fermare un lettore basta usare il comando '''stop''':
 stop player "esempio"

I comandi e le proprieta' dei lettori multimediali sono tantissime.

!!Audio

Per l'audio potete importare il file come le immagini: ''File -> Import as Control -> Audio File''. Quindi basta usare il comando '''play''' senza dover scomodare un lettore apposito:

 play audioClip "esempio"

per fermare l'audio basta aggiungere '''stop''':
 play stop

per impostare il volume basta usale la proprieta' '''playLoudness''' (si considera sempre un numero tra 0 e 100):

 set the playLoudness of audioclip "esempio" to 50 


13.5Working with Visual Transition Effects

LiveCode supports visual transition effects when changing card or hiding and showing
objects. There are three types of effect support: built-in effects which work on allplatforms, QuickTime effects which work on systems that have QuickTime installed and
Core Image effects which work on Mac OS 10.4 or later.

Use the visual effect command to display a visual effect. To go to the next card
with a dissolve transition effect:

visual effect dissolve slow
go next card

To make changes to objects on the screen with a visual effect (e.g. hide, show or movethem), first lock the screen, then make the changes, then unlock the screen:

lock screen
hide image 1show image 3unlock screen with visual effect "wipe right"

To choose a QuickTime effect using the effect chooser dialog use:

answer effect
-- store the visual effect as a custom propertyset the cEffect of this stack to it

Then:

February 28, 2014, at 02:59 PM by Massimiliano Vessi -
Changed lines 1903-1912 from:
12.3Externals – code written in lower level languages

LiveCode provides an external interface which allows you to extend it using a lower levellanguage (often C). For example, if you have preexisting code that performs processing
in a lower level language, you can write a user interface in LiveCode and then call thislibrary by writing a simple wrapper around it using LiveCode's externals interface.
LiveCode supports transmitting data to and from externals, as well as drawing into imageobjects within LiveCode windows, manipulating the player object, and more.

Note: Some aspects of the built in functionality are supplied in the form of externals.
These include the SSL library, the database library, the revBrowser library, zip library,
video grabber and XML libraries. These libraries can be included in a standalone
application, or excluded if they are not needed – saving disk space.
to:
!Lavorare con le immagini
Deleted lines 1904-1906:

!Lavorare con le immagini
 
Added lines 1980-1984:
!! Immagini vettoriali

Potete creare immagini vettoriali (quelle che non sgranano ingrandendole) sia con gli strumenti presenti nella ''Tool palette'' che il codice di programmazione.

Attach:LCVectorTools.jpg
February 27, 2014, at 05:53 PM by Massimiliano Vessi -
Changed lines 1947-2111 from:
13.1.4 Creating Images
To create an image, drag an image object from the Tools palette to your stack. You may
now paint on the image using the paint tools, set the fileName reference to an image or
manipulate the binary data of the image.

 
13.1.5 Using the Paint Tools
To access the paint tools, press the fold out triangle at the bottom right of the Toolspalette.


Figure 84 – The Graphic Tools


Tool Usage Keyboard modifiers
Select Drag to select a rectangular area of an Shift constraints to a
image square; command /
control duplicatesselection
Bucket Fills shapes with color. Will fill any pixelControl-click to fill
connected to the pixel you click with thewith transparency
brush color
Spray can Draw an airbrushed color using the brush Control-click to spray
shape with transparency
Eraser Remove color from an area leaving ittransparent. Uses the brush shape
Rectangle Draw a rectangle shape Shift constrains to a
square; controlcreates transparency
Rounded Draw a rounded rectangle shape (hold Shift constrains to a
rectangle down on the rectangle shape to select this square; controlshape) creates transparency
Oval Draw an oval shape (hold down on theShift constrains to a
rectangle shape to select this shape) square; controlcreates transparency
Regular Draw regular polygon shape (hold down Shift constrains to a
polygon on the rectangle shape to select this shape) square; constrainsrotation; control
creates transparency
Polygon Draw polygon shape (hold down on theShift constrains lines
rectangle shape to select this shape) angles to multiples of22.5°; control creates
transparency
Line Draw a straight line Shift constrains lines
angles to multiples of

 
22.5°; control creates
transparency
Freehand Draw a freehand curve (hold down on theAlt / option preventsline shape to select this shape). If the filled drawing line border;
option is chosen the beginning and end ofcontrol creates
the curve are joined automatically when transparency
you finish drawing
Pencil Draw a single-pixel-width freehand line Control creates
transparency
Brush Draw brush strokes using the brush shape Control creates
transparency;
command click to
magnify
Fill Select a color to fill shapes or use with the(brush) brush tools
color
Line Select a color to draw lines or use with the
color pencil tool
Brush Choose a brush shape for use with theshape brush, eraser and airbrush tools

To magnify an image, right click it with the pointer tool and choose Magnify from the
menu.

When you edit an image, it will be recompressed into the format specified by thepaintCompression global property.

13.1.6 Scripting with the Paint Tools
Painting by script can be useful if you want the user to be able to see each paint action. Ifyou want to manipulate the data of an image more efficiently off screen, see the nextsection.

To control the paint tools by script, create an image then choose the paint tool you wantto use. Set the appropriate brush, pattern or line size then use the drag command to paint.

The following example creates an image, chooses the brush tool, selects a small circular
brush shape, selects a red color, then draws a line:

-- set the size of the imageset the rect of the templateImage to 100,100,400,400create imagechoose brush tool
set the brush to 8
set the brushColor to red -- could use an RGB triplet hereset the dragSpeed to 20 -- very slowdrag from 120,120 to 300,300

 
For more information, see the entries for the templateImage, tool, brush,
brushColor, brushPattern, dragSpeed, penColor and penPattern in the
LiveCode Dictionary.

You may reduce the size of an image using the crop command.

You may rotate an image using the rotate command.

To adjust the quality of the scaling algorithm used when scaling an image, set theresizeQuality property before setting the image's rect.

13.1.7 Manipulating Binary Image Data
To manipulate the binary data of an image, use the image's imageData property. Thisproperty returns the color and transparency value of each pixel in the image in aconsistent format regardless of the format the image is saved in. The imageData is
stored as binary, with each pixel represented by 4 bytes. To convert it to and from RGB
values use the charToNum and numToChar functions.

For example, the numeric value of the red channel for the tenth pixel is given by theexpression charToNum(char ((4 * 9) + 2) of the imageData of
image). The numeric value of the green channel is charToNum(char (4 * 9) +
3 of the imageData of image); and the numeric value of the blue channel is
charToNum(char (4 * 9) + 4 of the imageData of image).

To manipulate the binary data of an image using an external, use the imagePixMapIDproperty.

When you set the imageData of an image the image will be recompressed into the
format specified by the paintCompression global property.

13.1.8 Rendering an Image from Objects
Use the import snapshot command to create an image from objects or a region of astack. Instead of specifying a rectangle in global coordinates (as described above) specify
a stack or object.

Note: Unlike screen capturing, the stack or object you specify to import an image from
does not need to be displayed on screen. You can create a layout off screen in an
invisible stack then render it into an image.
To import a snapshot of a region of a stack:

import snapshot from 100,100,200,200 of stack "Layout"

 
To import a snapshot of an object:

import snapshot from button 5 of stack "objects"

The import snapshot command creates a new image in the current defaultStack. The
image is encoded using the current paintCompression format.

To save this snapshot directly to a file instead of creating an image, use the exportsnapshot command:

export snapshot from the selectedObject to file "snap.jpg" as JPEG

13.1.9 Exporting Images
To export an image in the current format that it is stored in, put it into a binary file using
the URL commands. The following example prompts the user to select a file then exportthe image into it:

ask file "Select a file:"
put image "picture" into URL ("binfile:" & it)


To export an image in a different format, use the export command.

export image "picture" to file "picture.png" as PNG

You may also export an image to a variable. See the export command in the LiveCode
Dictionary for more information.

13.1.10 Copying and Pasting Images
To copy an image internally without using the system clipboard, simply put it into avariable or into another image.

put image 1 into image 2

To recompress the image in a different format, use the export command to export it to
a variable then put that variable into an image.

To copy an image to the clipboard, use the copy command.

copy image 1

To paste an image from the clipboard, use the paste command.

To transfer the binary data of an image to and from the clipboard get and set theclipBoardData["image"] property. See the clipBoardData entry in the
LiveCode Dictionary for more information.

 
13.1.11 Working with Animated GIFs
You can import an animated GIF image in the same way you import other images.

Set the repeatCount property to specify how often to play the animation. Setting the
repeatCount to 0 pauses the animation and setting it to -1 causes it to repeat forever.
To change the current frame set the currentFrame property.

Note: If you use an animated GIF as a button icon, it will play simultaneously in each
button it is used for.
to:
Se volete potete anche crearla con il codice vostro del programma, ad esempio:

 set the rect of the templateImage to 100,100,400,400
 create image "esempio"
 choose brush tool
 set the brush to 8
 set the brushColor to red
 set the dragSpeed to 20
 drag from "120,120" to "300,300"

Potete anche tagliare le immagini con '''crop''' e ruotarle con '''rotate'''.

Quando manipolatele immagini, cambiate il valore della proprieta' '''resizeQuality''' opportunamente.

Potete anche creare le immagini da estraendole da una porzione della finestra di un vostro programma, ad esempio:

 import snapshot from 100,100,200,200 of stack "Layout"

oppure da un elemento:

 import snapshot from button 5 of stack "objects"

!!Esportare immagini

Potete salvare le immagini in un file con la sintassi per scrivere i file:

 put image "miaimmagine" into URL "binfile:esempio.jpg"

oppure esportare l'immagine di una finestra direttamente in un file con il comando '''export''':

 export snapshot from the selectedObject to file "snap.jpg" as JPEG

il comando '''export''' vi permette di decidere il formato dell'immagine.

!!Copia e incolla con le immagini

E' valido scrivere il seguente comando:

 put image 1 into image 2


!!GIF animate

Le immagini GIF animate vi permetto di creare brevi animazioni. Potete utilizzarle come tutte le altre immagini, la proprieta' '''repeatCount''' vi permette di decidere quante volte ripeterel'animazione; il valore 0 blocca l'animazione, il valore -1 vi permette di ripetere l'animazione all'infinito.


13.2Working with Vector Graphics

In addition to bitmap graphics, LiveCode also supports vector graphics. You can createvector graphics using the graphics tools, or by script. You can manipulate theminteractively in the IDE or by script. You can relayer them, export a description of themor convert them to bitmap format.

Tip: Animation Engine is a 3rd party library that includes a set of functions for
programming interactive graphic animations. See the Related Software section of our
web site for more information.
13.2.1 The Vector Graphic Tools
To see the graphic tools, unfold the triangle at the bottom right of the tools palette. Thegraphics tools are located above the paint tools on the tools palette. The graphic toolsoperate in the same way as the paint tools, except that each time you draw a shape a newgraphic object is created. Unlike paint graphics, you can resize and adjust graphic objectsafter you have created them. For more information on the individual shapes, see thesection on Paint Tools, above.

13.2.2 Creating Graphics by Script
To create graphics by script, set properties of the templateGraphic then use the
create graphic command. For more information on template objects, see the
section Creating objects off screen using the template objects in Chapter 7.

13.2.3 Manipulating graphics by script
Because each graphic is an individual object, you manipulate its appearance by setting
properties rather than using the drag commands (as with the paint tools, above). You can
control all properties of the graphic object by script including the rectangle, line and fillproperties. You can change a graphic from one type to another (e.g. a rectangle to an
oval) by setting its style property.

February 27, 2014, at 05:22 PM by Massimiliano Vessi -
Changed line 1945 from:
to:
Attach:LCDisegnoTool.jpg
February 27, 2014, at 05:18 PM by Massimiliano Vessi -
Changed lines 1914-1938 from:
12.3.1 The Externals SDK
We provide a developer kit for writing externals which includes documentation and
examples. You may download this kit from:

http://downloads.runrev.com/resources/externals/revexternalssdk.zip

The following newsletter articles will also help you get started:
External Writing for the Uninitiated – Part 1

http://www.runrev.com/developers/tutorials/advanced-externals-part-1/

External Writing for the Uninitiated – Part 2

http://www.runrev.com/developers/tutorials/advanced-externals-part-2/

Writing Externals for Linux with 2.9 or later

http://www.runrev.com/developers/tutorials/advanced-linux-externals/

12.4Building a Web Application

Additional documentation for this section is being prepared for the next version ofLiveCode. In the mean time we recommend the comprehensive tutorial on this topic here:

http://www.hyperactivesw.com/cgitutorial/intro.html

to:

!Lavorare con le immagini
Changed lines 1917-1999 from:
Chapter 13 Working with Media

One of the most popular uses for LiveCode is to create full blown multimediaapplications. Even if you aren't creating a traditional multimedia application, many
applications require a compelling user interface.

This chapter details LiveCode's media support. We discuss the image features and
capabilities: how to import and export images in a variety of formats, how to manipulateimages within LiveCode, working with masks, the clipboard and screen capture, rightthrough to animated GIFs. We detail the vector graphic features and explain how to
manipulate vector graphics by script. We then cover the video and audio feature set. Then
we show you how to create custom themed buttons. Finally we given an overview of thesupport for visual transition effects.

 
13.1Bitmap Images

LiveCode supports a wide variety of image formats, including the popular PNG and
JPEG formats. PNG images are space efficient and have full support for alpha channels.
JPEG images are good for displaying photos. For more details see the table below.

Format

Export

Mask

Comments

PNG Yes Yes, 1-bit or Supports gamma adjustment, supports alphaalpha channel channels, supports interlacing
JPEG Yes No Supports progressive JPEGs; lossy compression.
Export allows you to set the level of compression
GIF Yes 1-bit GIF87a and GIF89a; supports animation; supportsinterlaced GIFs; maximum 256 colors
BMP No No Uncompressed
PBM Yes No 1-bit (black and white)
PGM No No Grayscale
PPM No No
XBM No No
XPM No No 1-bit (black and white)
XWD No No
PICT No No uncompressed

As you can see from the table above, a number of the supported image formats can also
be exported by LiveCode.

You can modify images using LiveCode's paint tools, or manipulate the binary data by
script or using an external.

You can create images from any of LiveCode's native objects, including buttons, fieldsand graphics. These can then been exported in a number of formats. You can copy
images from the clipboard or export images to the clipboard.

LiveCode can capture a portion of the screen, or the entire screen.

13.1.1 Importing Images
To import an image, choose File -> Import As Control -> Image File. Select the imagefile you want to import. This will import the image file into a new image object on thecurrent card. This is equivalent to executing the import paint command in the
Message Box.

Note: If you want to reuse an image throughout your application, for example as part ofa custom skin for your application, create a substack and import all your images into that.
 
You can then reference them throughout your stack file. For more information, see thesection Creating Custom Skins, below.
13.1.2 Importing Referenced Images
To reference an image file on disk choose File -> New Referenced Control -> Image File.
This creates an image object on the current card and sets its fileName property to thepath of the image file you selected. Referenced images do not expand the size of your
stack and are only loaded from disk into memory when you navigate to the current card
or otherwise display them on screen. Referenced images are ideal where you want to
update the image in an image editor and see the changes in LiveCode without having to
re-import.

You may wish to consider creating a folder next to your stack file to contain image filesthen using the Inspector to modify the file path to the image to be a referenced path. Thisallows you to move the stack and folder of images together onto a different system. for
more information on referenced file paths, see the section File Name Specifications and
Paths.

You can use the standalone builder to copy referenced images into a directory (updating
each image's fileName property) or to copy referenced images into your stack. For
more information see the chapter Deploying your Application.

Important: You cannot use the paint tools or manipulate the binary data of referenced
images. You must import them first. If you want to modify the original file, you can
make changes then export the image – see below for more details.
13.1.3 Import using Screen Capture
To import an image by capturing a portion of the screen, choose File -> Import AsControl -> Snapshot. Select the region of the screen you want to import.

To take a screen capture by script, use the import snapshot command. To specify asection of the screen to import from without displaying the crosshairs use importsnapshot from rect:

import snapshot from 100,100,200,200

This will create an image object on the current card from the rectangular area specified.
to:
Livecode supporta tantissimi tipi di immagini, chiaramente il formato migliore e' il PNG che ha anche le trasparenze.
Ecco i principali:
*PNG
* JPEG
*GIF
*BMP
* PBM
* PGM
* PPM
* XBM
*XPM
*XWD
*PICT

!!Importare immagini

Per importare immagini dentro il vostro programma, basta andare su ''File -> Import As Control -> Image File''. L'immagine sara' caricata dentro Livecode e apparira' nella finestra corrente. All'immagine sara' anche assegnato un '''ID''' che potrete usare come riferimento ogni volta che vorrete usarla.

Si puo' importare un'immagine anche solo come riferimento, ma non viene salvata dentro al programma, viene memorizzato solo il percorso relativo della sua posizione. Io sconsiglio questo modo, perche' se spostate la cartella del programma, non ritroverete piu' le immagini. Importarle per riferimento ha senso solo se avete migliaia di immagini e non volete appesantire troppo il programma.

Potete importare anche un'istantanea dello schermo (''screenshot''), basta andare su ''File -> Import AsControl -> Snapshot'', oppure con il comando:

 import snapshot from 100,100,200,200

!!Creare immagini

Se inserite nella finestra un'immagine (vuota o piena), potete modificarla con gli strumenti per disegnare della ''Tool palette''.



13.1.4 Creating Images
To create an image, drag an image object from the Tools palette to your stack. You may
now paint on the image using the paint tools, set the fileName reference to an image or
manipulate the binary data of the image.

February 26, 2014, at 06:15 PM by Massimiliano Vessi -
February 26, 2014, at 05:52 PM by Massimiliano Vessi -
Changed lines 1895-1984 from:

12.2.1 Creating Plug-ins
You can create a plug-in to help perform tasks that you need to do regularly in theLiveCode IDE. Plug-ins are written as LiveCode stacks. (If you need to extend LiveCodeusing a lower level language, see the section on Externals, below.)

To create a plug-in, save your stack into the Plugins folder, located within the My
LiveCode [Edition] folder, inside your Documents folder.

You can now load your stack by choosing its name from the Development -> Pluginssubmenu. By default your plug-in will be loaded as a palette. This allows you to operatethe controls in the plug-in while the LiveCode IDE is in pointer tool mode. This allowsyou to create custom "Property Inspector" style behaviors or other object editing tools.

The Plugin Settings Screen

 
Open the Plugin settings screen from the Development -> Plugins submenu. Choose theplugin you have created from the Plugin menu at the top of the screen to apply settings to
it.


Figure 83 – The Plugin Settings Screen

Open plugin when:

By default your plugin will load when you chose it from the plugins menu. If you want to
have your plugin load whenever you start LiveCode select the "LiveCode starts up". Usethis if your plugin is used to set up your environment, for example by loading stacks thatyou are working on or adjusting window layout. To have your plugin load when
LiveCode quits choose "LiveCode quits". Use this if your plugin performs clean up tasksthat you want to have run whenever you exit.

Open as:

Choose the mode you want your plugin to open as. If you choose the invisible option,
your plugin stack will be loaded invisible. Use this option to create a plugin that installs afaceless library (for example by inserting a button within it into the front or backscripts)
or to perform some other automated task that does not require a visible user interface.

 
Note: Loading from your plugin will not allow you to edit the plugin itself. If you want
to edit the plugin, first load it from the menu then use the Application Browser to make it
toplevel by right clicking on it in the list of stacks and choosing Toplevel from the popup
menu.
Send messages to plugin:

In order to have your plug-in respond as you work in the IDE you need to register it to
receive messages. The IDE can send a variety of messages to the current card in your
plug-in as you change selection, switch tools, open and close stacks, etc. The messagesthat can be sent are listed below.

Message Sent when
revCloseStack The user closes a stack in the IDE
revEditScript The user chooses "edit script"
revIDChanged The ID of an object is changed
revMouseMove The mouse is moved
revMoveControl A control is moved with the pointer tool
revNameChanged The name of an object is changed
revNewTool A new tool is chosen
revPreOpenCard A preOpenCard message is sent on changing card
revPreOpenStack A preOpenStack message is sent on opening stack
revResizeControl A control is resized using the pointer tool
revResizeStack A stack is resized
revResumeStack A stack is activated
revSaveStackRequest The save command is executed
revSelectedObjectChanged The selection is changed with the pointer tool
revSelectionChanged The text selection is changed
revShutdown LiveCode is quit

Tip: Internally the IDE implements these plugin messages by intercepting system
messages sent my LiveCode in the IDE frontScripts and backScripts then sending out a
corresponding message to any loaded plugin. You can look up these messages in the
LiveCode Dictionary by removing the "rev" in front of the messages above.
For example, to have your plugin update whenever an object is selected with the pointer
tool, select the revSelectedObjectChanged message. Then insert the following
handler into your plugin card script:

on revSelectedObjectChanged-- store the list of selected objectsput the selObj into tObjectsListrepeat for each line l in tObjectsList

-- insert code to operate on each object here

 
 end repeatend revSelectedObjectChanged

12.2.2 Editing the IDE
Caution: Editing the IDE can easily cause LiveCode to become unusable. We
recommend that only advanced users attempt to edit the IDE. We recommend you backup the IDE prior to making any changes. We do not recommend attempting to edit theIDE while working on any mission critical project.
To edit the LiveCode IDE, turn on LiveCode UI Elements in Lists in the View menu. This
causes LiveCode to display its own stacks within the Application Browser and other
editing screens. You can now load these stacks to edit them. To allow you to editLiveCode IDE objects with the keyboard shortcuts, turn on the In LiveCode UI Windows
and Contextual menus work in LiveCode Windows, options in the Preferences.

The IDE uses the stack revLibrary to provide much of its functionality. The scripts arestored as a series of buttons and loaded into the frontScripts and backScriptswhen the IDE is started. To edit these scripts, go to the Front Scripts or Back Scripts tab
within the Message Box and check the "Show LiveCode UI Scripts" checkbox.

Caution: If you make a mistake editing revFrontScript or revBackScript, LiveCode will
become non-responsive and you will have to force-quit.
The Code Editor and Property Inspector functionality is provided by two stacks,
revTemplateScriptEditor and revTemplatePalette. These stacks are cloned each time you
open a new Script Editor or Inspector. To make permanent changes you need to apply thechanges to these stacks and save them.
to:
!Plugin
Potete scrivere ''plug in'' (componenti aggiuntivi) per il vostro Livecode IDE semplicemente copiando il file del vostro programma nella cartella ''Plugins'' di Livecode.

Una volta fatto cio' troverete il vostro plugin nella lista del menu ''Development -> Plugins''.
Nel menu ''Development -> Plugins-> Plugin Settings''  potete decidere quali plugin avviare automaticamente insieme a Livecode.



12.3Externals – code written in lower level languages

LiveCode provides an external interface which allows you to extend it using a lower levellanguage (often C). For example, if you have preexisting code that performs processing
in a lower level language, you can write a user interface in LiveCode and then call thislibrary by writing a simple wrapper around it using LiveCode's externals interface.
LiveCode supports transmitting data to and from externals, as well as drawing into imageobjects within LiveCode windows, manipulating the player object, and more.

Note: Some aspects of the built in functionality are supplied in the form of externals.
These include the SSL library, the database library, the revBrowser library, zip library,
video grabber and XML libraries. These libraries can be included in a standalone
application, or excluded if they are not needed – saving disk space.
February 26, 2014, at 05:44 PM by Massimiliano Vessi -
Changed lines 1877-2033 from:

Chapter 12 Extending the Built-in Capabilities

This chapter covers how to extend the built-in capabilities of LiveCode. This topic isuseful for anyone who wants to extend the feature set of LiveCode. It is also useful if you
are planning to use LiveCode as a front-end to any existing application or set of
processes.

There are many ways to extend LiveCode. This topic explains how to run shellcommands, start other applications, read and write to processes, execute AppleScript,
VBScript, send and respond to AppleEvents and communicate between multipleLiveCode-based processes. It also tells you where to get information to create externalcommands and functions (code written in lower level languages). We also detail how to
extend the LiveCode IDE: how to create a plug-in or edit the IDE itself.

 
12.1Communicating with other process and applications

12.1.1 Reading and writing to the command shell
Use the shell function to run shell commands and return the result. The following
example displays a directory listing on Mac OS X:

answer shell("ls")

And this example stores a directory listing in a variable on Windows:

put shell("dir") into tDirectory

On Windows systems you can prevent a terminal window from being displayed by
setting the hideConsoleWindows global property to true.

You can choose a different shell program by setting the shellPath global property. By
default this is set to "/bin/sh" on Mac OS X and Linux and "command.com" on Windows.

Tip: The shell function blocks LiveCode until it is completed. If you want to run a shellcommand in the background, write the shell script to a text file then execute it with the
launchcommand.
12.1.2 Launching other applications
Use the launch command to launch other applications, documents or URLs. To launch
an application, supply the full path to the application. The following example opens a textdocument with TextEdit on OS X:

launch "/Users/someuser/Desktop/text document.rtf" with \
"/Applications/TextEdit.app"

Tip: To get the path to an application, use the answer file command to select theapplication then copy it into your script. Run this in the message box: answer file
"Select an application"; put it
To open a document with the application it is associated with use the launch
document command.

launch document "C:/My document.pdf"

To open a URL in the default web browser, use the launch URL command.

 
launch URL "http://www.runrev.com/"

For more information on launching URLs see chapter 12. For details on how to render
web pages within LiveCode, see the section on revBrowser.

12.1.3 Closing another application
Use the kill process command to send a signal to another application, to close it or
to force it to exit. For more details, see the LiveCode Dictionary.

12.1.4 Communicating with other processes
Use the open process command to open an application or process you want to read
and write data from. You can then read from the process with the read from
process command and write to it with the write to process command. To close
a process you have opened, use the close process command. The
openProcesses returns a list of processes you have opened and theopenProcessIDs returns the process IDs of each one. For more details see the
LiveCode Dictionary.

12.1.5 Using AppleScript and VBScript (Open Scripting Architectureor Windows Scripting Host)
To execute commands using AppleScript on Mac OS or VBScript on Windows, use thedo as command. do as also allows you to use any other Open Scripting Architecture
languages on Mac OS or languages installed into the Windows Scripting Host on
Windows. To retrieve a list of the available installed languages, use thealternateLanguages.

For example, to execute an AppleScript that brings the Finder on OS X to the front, enter
the following into a field:

tell application "Finder"

 activate
end tell

Then run:

do field 1 as "appleScript"

To retrieve a result from commands executed using do as, use the result function.
Any error message will also be returned in the result. The following exampledisplays the result of an addition performed using VBScript:

do "result = 1 + 1" as "vbscript"
answer the result

For more information on the do as command, see the LiveCode Dictionary.

 
12.1.6 AppleEvents
To send an AppleEvent, use the send to program command.

If LiveCode receives an AppleEvent it will send an appleEvent message to the currentcard. Intercept this message to perform actions such as handling a request to quit your
application or opening a document. The following example shows how you could handlea request to quit:

on appleEvent pClass, pID, pSender
if pClass & pID is "aevtquit" then
--call a function that prompts the user to save changesput checkSaveChanges() into tOkToQuit-- returns false if the user presses "cancel"
if tOkToQuit is true then quitelse exit appleEventend if
end appleEvent

To retrive additional information passed with the appleEvent use the requestappleEvent data command. The following example shows how you could handle arequest to open a stack:

on appleEvent pClass, pID, pSender

--appleEvent sent when stack is opened from the finder

if pClass & pID is " aevtodoc " then

-- get the file path(s)

request AppleEvent data

put it into tFilesList

 repeat for each line l in tFilesList

go stack lend repeatend appleEvent

For more details see the LiveCode Dictionary.

12.1.7 Using Local sockets
If you want to communicate between local applications a common technique that can beused without code changes on all the platforms LiveCode supports, is to open a localsocket and communicate using that. You should choose a port number that is not used by
a standard protocol – typically a high number.

This technique is commonly used when you want to create multiple programs that run
independently but communicate with each other. It is a viable technique for running
background tasks and provides a straightforward way to create an application thatbehaves as if threaded – i.e. with benefits of multiple threads. You can design your
application such that additional instances can be launched to perform processing, datatransfer or other intensive activities. Modern OSes will allocate each application to an

 
appropriate processor core. By using socket messaging to communicate with each oneyou can keep your main application's user interface responsive and display statusinformation. The following example shows you how to open a socket to the localmachine:

open socket to "127.0.0.1:10000" with message gotConnection

A detailed discussion of how to create a protocol using sockets can be found in chapter

12.
Tip: To simplify communication between multiple LiveCode programs, consider writing
a simple library that sends and receives a handler name together with parameter data. To
call a handler in the other LiveCode program, send the handler name and data to thelibrary. The library will send the data over a socket. In the receiving program intercept
the incoming data from the socket and use it to call the appropriate message with the
parameter data received.
12.2Extending the LiveCode IDE

The LiveCode IDE (integrated development environment) has been written using
LiveCode. All the components – the Tools Palette, Property Inspector, Script Editor,
Debugger, etc., are implemented as LiveCode stacks. The IDE has a series of library
frontScripts and backScripts it uses to provide functionality both for the IDE and for your
application. Some of these libraries are used only by the IDE (e.g. the debugger library),
others (e.g. the Internet library, libURL) are copied into your standalone by thestandalone builder.

This design makes it easy to extend the IDE with plug-ins. If you are an advanced
LiveCode developer you can also edit the IDE itself to provide custom functionality.
to:
Potete anche utilizzare il terminale da dentro il vostro programma, sfruttando la funzione '''shell()'''; ecco un esempio su Linux:

 put shell("ls -a") into listafiles

l'unico inconveniente di '''shell()''' e' che il programma si blocca finche' non ha finito di eseguire il comando.

Un altro modo per poter interagire con il sistema operativo e' il comando '''launch'''. Potete lanciare altri programmi, esempio:

 launch "/home/max/esempio.txt" with "/usr/bin/gedit"

se il sistema operativo ha associato un programma predefinito a certi tipi di file, potete semplicemente lanciare il file con la parola '''document'''; esempio:

 launch document "C:/documento.pdf"

per avviare il browser predefinito basta usare la parola '''URL''':

 launch URL "http://www.livecode.com/"


12.2.1 Creating Plug-ins
You can create a plug-in to help perform tasks that you need to do regularly in theLiveCode IDE. Plug-ins are written as LiveCode stacks. (If you need to extend LiveCodeusing a lower level language, see the section on Externals, below.)

To create a plug-in, save your stack into the Plugins folder, located within the My
LiveCode [Edition] folder, inside your Documents folder.

You can now load your stack by choosing its name from the Development -> Pluginssubmenu. By default your plug-in will be loaded as a palette. This allows you to operatethe controls in the plug-in while the LiveCode IDE is in pointer tool mode. This allowsyou to create custom "Property Inspector" style behaviors or other object editing tools.

The Plugin Settings Screen

February 26, 2014, at 05:35 PM by Massimiliano Vessi -
Changed lines 1859-1860 from:

to:
!Uso da linea di comando
Livecode e' un linguaggio di programmazione grandioso per programmi grafici, comunque puo' essere utilizzato anche da linea di comando. Se per esempio scrivete un programma e lo chiamate "esempio.livecode" potete lanciarlo da line dicomando cosi':

 livecode  esempio.livecode

se poi il vostro programma ha bisogno di parametri, potete metterli dopo, esempio:

 livecode  esempio.livecode param1 -h 52 --parametro-4

ogni parametro e' memorizzato in una variabile globale sempre accessibile numerata, nell'esempio precedente abbiamo:

* $0 = esempio.livecode (il nome del programma)
* $1 = "param1" (primo parametro)
* $2 = "-h" (secondo parametro)
* $3 = "52" (terzo parametro)
* $4 = "--parametro-4" (quarto parametro)


Deleted lines 2757-2772:
!Uso da linea di comando
Livecode e' un linguaggio di programmazione grandioso per programmi grafici, comunque puo' essere utilizzato anche da linea di comando. Se per esempio scrivete un programma e lo chiamate "esempio.livecode" potete lanciarlo da line dicomando cosi':

 livecode  esempio.livecode

se poi il vostro programma ha bisogno di parametri, potete metterli dopo, esempio:

 livecode  esempio.livecode param1 -h 52 --parametro-4

ogni parametro e' memorizzato in una variabile globale sempre accessibile numerata, nell'esempio precedente abbiamo:

* $0 = esempio.livecode (il nome del programma)
* $1 = "param1" (primo parametro)
* $2 = "-h" (secondo parametro)
* $3 = "52" (terzo parametro)
* $4 = "--parametro-4" (quarto parametro)
February 26, 2014, at 05:18 PM by Massimiliano Vessi -
Added lines 1773-1780:
Se inviate un file in una directory che non esiste, la directory verra' creata automaticamente. Il metodo migliore per creare una directory e' inviandogli ''empty'' come file:

 put  empty into URL "ftp://user:password@ftp.maxvessi.net/nuovacartella/"

NOTA: Se volete usare nomi con caratteri speciali o spazi in un URL, potete passare attraverso la funzione '''URLEncode''':

 put URLEncode("ftp://user:password@ftp.maxvessi.net/nuovacartella/Nuova cartella/") into miourl
 put  empty into URL miourl
Changed lines 1843-2122 from:
!!Riempire i dati di un form web

La funzione '''libUrlFormData''' invia i dati attraverso i
 
11.6.1 Working with Web Forms
To post data to a web form, use the post command. To encode data to make it suitable
for posting, use the libUrlFormData function. To create multi-part form data (as
described in RFC 1867) use the libUrlMultipartFormData function. To add data
to a multipart form one part at a time, use the libUrlMultipartFormAddPartfunction. This can be useful if you need to specify the mime type or transfer encoding for
each part.

11.6.2 Working with FTP
For details on basic uploading and downloading using FTP, see the section above.


The following commands provide additional capabilities when working with the ftp
protocol:


libURLSetFTPStopTime-Sets the timeout value for FTP transfers.
libURLSetFTPMode-Switches between active and passive mode for FTP transfers.
libURLSetFTPListCommand-Switches between sending LIST or NLST formats
when listing the contents of an FTP directory.
libURLftpCommand– sends an ftp command to an ftp server.
libURLftpUpload– uploads data. See the section above for more details.
libURLftpUploadFile– uploads a file, without loading the entire file into memory.
See the section above for more details.
libURLDownloadToFile– downloads data to a file, without loading the entire data
into memory. See the section above for more details.


11.6.3 HTTP methods and http URLs
The basic operations used by the HTTP protocol are called methods. For http URLs,
the following HTTP methods are used under the following circumstances:

* GET: when an http URL in an expression is evaluated
 
* PUT: when you put a value into an http URL
* POST: when you use the post command
* DELETE: when you use the delete URL command with an http URL
Note: Many HTTP servers do not implement the PUT and DELETE methods, whichmeans that you can't put values into an http URL or delete an http URL on such servers.
It's common to use the FTP protocol instead to upload and delete files; check with your
server's administrator to find out what methods are supported.
HTTP headers

When LiveCode issues a GET or POST request, it constructs a minimal set of HTTPheaders. For example, when issued on a Mac OS system, the statement:

put URL "http://www.example.org/myfile" into myVariable

results in sending a GET request to the server:

 GET /myfile HTTP/1.1
Host: 127.0.0.0
User-Agent: LiveCode (MacOS)


You can add headers, or replace the Host or User-Agent header, by setting theHTTPHeaders property before using the URL:

set the HTTPHeaders to "User-Agent: MyApp" \
& return & "Connection: close"
put URL "http://www.example.org/myfile" into myVariable

Now the request sent to the server looks like this:

 GET /myfile HTTP/1.1
Host: 127.0.0.0
User-Agent: MyApp
Connection: close


The ftp URL scheme can be used to create a new file to an FTP server. As with the file
and binfile schemes, putting something into the URL creates the file:

put dataToUpload \
into URL "ftp://jane:pass@ftp.example.com/newfile.dat"

 
Tip: You can create an FTP directory by uploading a file to the new (nonexistent)
directory. The directory is automatically created. You can then delete the file, if you
wish, leaving a new, empty directory on the server:
-- Create an empty file in the nonexistent directory:
put empty into \

URL "ftp://jane:pass@example.com/newdir/dummy"
-- Delete unwanted empty file to leave new directory:
delete URL "ftp://jane:pass@example.com/newdir/dummy"

11.6.4 Additional Transmission Settings
The following commands provide additional customization options for the Internet
library:


libUrlSetExpect100– Allows you to set a limit to the size of data being posted
before requesting a continue response from the server.
libURLSetCustomHTTPHeaders-Sets the headers to be sent with each request to
an HTTP server. See also the section on HTTPHeaders above.
libURLFollowHttpRedirects– Specify that GET requests should follow HTTP
redirects and GET the page redirected to.
libUrlSetAuthCallback- Sets a callback for handling authentication with http
servers and proxies.


11.6.5 Troubleshooting
The following commands and functions can be useful when debugging an application thatuses the Internet library.

resetAll-Closes all open sockets and halts all pending Internet operations.
Caution: The resetAllcommand closes all open sockets, which includes any othersockets opened by your application and any sockets in use for other uploads anddownloads. Because of this, you should avoid routine use of the resetAllcommand.
Consider using it only during development, to clear up connection problems duringdebugging.
libURLErrorData-Returns any error that was caused during a download that was
started with the load command.
libURLVersion– Returns the version of the Internet library.
libURLSetLogField– Specifies a field for logging information about uploads and
downloads on screen.
libURLLastRHHeaders-Returns the headers sent by the remote host in the most
recent HTTP transaction.
libURLLastHTTPHeaders-Returns the value of the httpHeadersproperty used for
the previous HTTP request.


 
11.7revBrowser – Rendering a Web Page within a Stack

Use the revBrowser commands to render a web page within a stack. RevBrowser usesWebKit (Safari) on Mac OS X and Internet Explorer on Windows. Currently RevBrowser
is not supported under Linux.

To create a browser object in a stack, use the revBrowserOpen function. This
function takes the windowID for the stack you want to open the browser in and a URL.
Please note that the windowID is not the same as the stack's ID property.

put the windowid of this stack into tWinIDput revBrowserOpen(tWinID,"http://www.google.com") \

into sBrowserId

To set properties on the browser, use the revBrowserSet command. The following
commands makes the border visible then sets the rectangle to be the same as an imagenamed "browserimage":

revBrowserSet sBrowserId, "showborder","true"
revBrowserSet sBrowserId, "rect",rect of img "browserimage"

To close a browser when you finished with it, use the revBrowserClose command.
This command takes the windowID for the stack containing the browser:

revBrowserClose sBrowserId

RevBrowser supports a number of settings and messages. You can intercept a messagewhenever the user navigates to a link, prevent navigation, intercept clicks in the browser,
requests to download files or to open a new window.

To try out all these options in an interactive format, download the Internet workshop
from:

http://www.runrev.com/developers/exploring-LiveCode/the-internet/

Click on the Render a Web Page example, press Run and then explore the revBrowser
Demo Stack.

For a complete list of commands that operate on RevBrowser, press the Show Docs
button in the revBrowser Demo Stack, or open the LiveCode Dictionary and type
"browser" into the filter box.

11.8SSL and Encryption

LiveCode includes support for using Secure Sockets Layer and the https protocol. It also
includes an industrial strength encryption library you can use to encrypt files or datatransmissions.

 
11.8.1 Encrypting and Decrypting Data
To encrypt data, use the encrypt command. The encrypt command supports a widevariety of industry standard methods of encryption. The list of installed methods can beretrieved by using the cipherNames function. To decrypt data, use the decryptcommand. For more information on these features, see the LiveCode Dictionary.

Tip: If you are using the encryption library on a Windows system, it is possible that
another application will have installed DLLs that use the same name as the ones included
with LiveCode to support encryption. You can force your application to load LiveCode's
SSL DLLs by setting the $PATH environment variable before loading the library.
Tip: put $PATH into tOldPathput <path to SSL DLLs> into $PATHget the cipherNames -- Force loading of the SSL DLLsput tOldPath into $PATH
11.8.2 Connecting using HTTPS
You may connect and download data from a URL using https in the same way that you
access an http URL.

put URL "https://www.example.com/store.php"

If there is an error, it will be placed into the result. If you need to include a user
name and password you can do so in the following form:

https://user:password@www.example.com/

11.8.3 Implementing your own secure protocols
To implement your own secure protocol, use the open secure socket variant of
the open socket command. You can specify whether or not to include certification, acertificate and a key. For more information on the open socket command, see the
LiveCode Dictionary.

11.9Writing your own protocol with sockets

If you need to implement your own protocol, you can do so using LiveCode's socket
support. To understand this chapter it is assumed you understand the basics of how theInternet works, including the concepts of sockets, IP addresses and ports. Moreinformation on these concepts can be found in Wikipedia.

Tip: The standard protocols that LiveCode support such as http and ftp, discussed earlier
in this chapter, have all been implemented as a scripted library with LiveCode's socket
support. You can examine this library by running edit script of button"revlibURL" of stack "revLibrary"in the Message Box. Beware, this
 
library is not for the feint of heart. If you change anything, LiveCode's Internet
commands may cease to operate.
Opening a connection

To open a connection use the open socket command. The following command opens
a connection to the IP address specified in the tIPAddress variable and the port
specified in the tPort variable. It specifies that LiveCode should send the message
"chatConnected" when a connection has been established.

open socket (tIPAddress & ":" & tPort) with message \
"chatConnected"

To open a secure socket, use the open secure socket variant of the command. To
open a UDP datagram socket, use the open datagram socket variant of the
command. For more information on these variants, see the LiveCode Dictionary.

Looking up a host name or IP address

You may look up an IP address from a host name with the hostNameToAddress
function. For example, to get the IP address for the runrev.com server:

put hostNameToAddress("www.runrev.com") into tIPAddress

To get the host name of the local machine, use the hostName function. To look up the
name from an IP address, use the hostAddressToName function.

Reading and writing data

Once LiveCode opens a connection, it will send a chatConnected message. To
receive data, use the read from socket command. The following message reads
data from the socket and sends a chatReceived message when reading is completed.

on chatConnected pSocket

read from socket pSocket with message chatReceivedend chatConnected

Once reading from the socket is completed the chatReceived message can be used to
process or display the data. It can then specify that it should continue to read from thesocket until more data is received, sending another chatReceived message when
done.

on chatReceived pSocket, pData

put pData after field "chat output"

read from socket pSocket with message "chatReceived"
end chatReceived

To write data to the socket, use the write command:

 
write field "chat text" to socket tSocket

Disconnecting

To disconnect, use the close socket command. You should store a variable with
details of any open sockets and close them when you have finished using them or when
your stack closes.

close socket (tIDAddress & ":" & tPort)

Listening for and accepting incoming connections

To accept incoming connections on a given port, use the accept connectionscommand. The following example tells LiveCode to listen for connections on port 1987
and send the message chatConnected if a connection is established. You can then
start to read data from the socket in the chatConnected handler.

accept connections on port 1987 with message chatConnected

Handling errors

If there is an error, LiveCode will send a socketError message with the address of
the socket and the error message. If a socket is closed a socketClosed message will
be sent. If a socket times out waiting for data a socketTimeout message will be sent.
To get a list of sockets that are open, use the openSockets function. You can set the
default timeout interval by setting the socketTimeOutInterval property. For more
details on all of these features, see the LiveCode Dictionary.

Tip: You can see a complete implementation of a basic client server "chat" application
by navigating to Documentation -> Getting Started -> Sample Projects -> Internet Chat –
creating a custom protocol using sockets -> Launch. Most of the scripts for the "server"
stack are in the "start server" button. Most of the scripts for the client are in the stack
script for the "chat client" stack.
to:
!!Riempire i dati di un form web e altro ancora

Tutti i comandi che cominciano per ''libURL''  vi permetto di fare cose incredibili via internet, cercateli sul dizionario. Potrete interagire con i siti e creare applicazioni distribuite e per cloud. Potete utilizzare anche i ''socket'', ecco alcuni esempi:

 open socket (tIPAddress & ":" & tPort) with message "chatConnected"
 on chatConnected pSocket
    read from socket pSocket with message chatReceived
 end chatConnected
 on chatReceived pSocket, pData
  put pData after field "chat output"
  read from socket pSocket with message "chatReceived"
 end chatReceived
 write field "chat text" to socket tSocket
 close socket (tIDAddress & ":" & tPort)




Chapter 12 Extending the Built-in Capabilities

This chapter covers how to extend the built-in capabilities of LiveCode. This topic isuseful for anyone who wants to extend the feature set of LiveCode. It is also useful if you
are planning to use LiveCode as a front-end to any existing application or set of
processes.

There are many ways to extend LiveCode. This topic explains how to run shellcommands, start other applications, read and write to processes, execute AppleScript,
VBScript, send and respond to AppleEvents and communicate between multipleLiveCode-based processes. It also tells you where to get information to create externalcommands and functions (code written in lower level languages). We also detail how to
extend the LiveCode IDE: how to create a plug-in or edit the IDE itself.

February 26, 2014, at 04:07 PM by Massimiliano Vessi -
Changed lines 1814-1822 from:

!!FTP con grossi file


Se i vostri file sono veramente grossi


libURLftpUpload uploads data to an FTP server

to:
!!Aprire il browser

Per aprire il browser del vostro sistema operativo basta usare il comando '''launch''':

 launch URL "http://www.maxvessi.net"

!!Inviare email

Per inviare email il metodo migliore e' utilizzare il comando '''launch''', ad esempio il seguente comando scrive ad una serie di persone sia direttamente, che in copia e copia nascosta:

 launch url "mailto:someone@example.com,anotherone@example.com?cc=someoneelse@example.com&bcc=andsomeoneelse@example.com&subject=Summer%20Party&body=You%20are%20invited%20to%20a%20big%20summer%20party!"

E apparira':

'''TO:''' someone@example.com,anotherone@example.com \\
'''CC:''' someoneelse@example.com \\
'''BCC:''' andsomeoneelse@example.com \\
'''Subject:''' Summer Party \\
You are invited to a big summer party!


!!Riempire i dati di un form web

La funzione '''libUrlFormData''' invia i dati attraverso i
Deleted lines 1838-1969:
libURLftpUploadFile uploads a file to an FTP serverlibURLDownloadToFile downloads a file from an FTP server to a local file

The basic effect of these commands is the same as the effect of using URLs: that is, thedata is transferred to or from the server. However, there are several differences in howthe actual file transfer is handled. Because of these differences, the library commands aremore suitable for uploads and downloads, particularly if the file being transferred is large.

The following sets of statements each show one of the Internet library commands, with
the equivalent use of a URL:

libURLftpUpload myVar,"ftp://me:pass@example.net/file.txt"
put myVar into URL "ftp://me:pass@example.net/file.txt"

libURLftpUploadFile "test.data","ftp://ftp.example.org/test"
put URL "binfile:test.data" into URL "ftp://ftp.example.org/test"

libURLDownloadToFile \
"ftp://example.org/new_beta","/HD/File"
put URL "ftp://example.org/new_beta" \
into URL "binfile:/HD/File"

Using callback messages

When you start a file transfer using the libURLftpUpload,
libURLftpUploadFile, or libURLDownloadToFile command, you can
optionally specify a callback message, which is usually a custom message that you writea handler for. This message is sent whenever the file transfer's URLStatus changes, so
you can handle the callback message to handle errors or to display the file transfer's statusto the user.

The following simple example demonstrates how to display a status message to the user.
The following handlers might be found in a button's script:

on mouseUp
libURLDownloadToFile "ftp://example.org/new_beta",\
"/HD/Latest Beta","showStatus"
end mouseUp

on showStatus theURL
put the URLStatus of theURL into field "Status"
end showStatus

When you click the button, the mouseUp handler is executed. The
libURLDownloadToFile command begins the file transfer, and its last parameter

 
specifies that a showStatus message will be sent to the button whenever the URLStatus
changes.

As the URLStatus changes periodically throughout the download process, the button's
showStatus handler is executed repeatedly. Each time a showStatus message is sent, thehandler places the new status in a field. The user can check this field at any time during
the file transfer to see whether the download has started, how much of the file has been
transferred, and whether there has been an error.

If a file transfer was started using the libURLftpUpload, libURLftpUploadFile, orlibURLDownloadToFile command, you can cancel the transfer using the unload
command.

Uploading, downloading, and memory

When you use a URL as a container, LiveCode places the entire URL in memory. For
example, if you download a file from an FTP server using the put command, LiveCodedownloads the whole contents of the file into memory before putting it into thedestination container. If the file is too large to fit into available memory, a file transfer
using this method will fail (and may cause other unexpected results).

The library commands libURLftpUpload, libURLftpUploadFile, and
libURLDownloadToFile, however, do not require the entire file to be loaded into
memory. Instead, they transfer the file one piece at a time. If a file is (or might be) too
large to comfortably fit into available memory, you should always use the library
commands to transfer it.

11.5.2 Using a stack on a server
Ordinarily, you use stack files that are located on a local disk. You can also open and use
a stack that is located on an FTP or HTTP server. Using this capability, you can update
an application by downloading new stacks, make new functionality available via the
Internet, and even keep most of your application on a server instead of storing it locally.


Going to a stack on a server:
As with local stack files, you use the go command to open a stack that's stored on a
server:


go stack URL "http://www.example.org/myapp/main.rev"
go stack URL "ftp://user:pass@example.net/secret.rev"

 Note: For such a statement to work, the stack file must have been uploaded as binary
data, uncompressed, and not use encodings such as BinHex.

 
Tip: If you need to download a large stack, use the loadcommand to complete thedownload before using the gocommand to display the stack. This allows you to displaya progress bar during the download.
LiveCode automatically downloads the stack file. The main stack of the stack file then
opens in a window, just as though you had used the go command to open a local stack
file.

You can go directly to a specific card in the stack:

go card "My Card" \
of stack URL "http://www.example.org/myapp/main.rev"

To open a substack instead, use the substack's name:

go stack "My Substack" \
of URL "http://www.example.org/myapp/main.rev"

Using a compressed stack

You cannot directly open a stack that's compressed. However, since the stack URL is acontainer, you can use the URL as the parameter for the decompress function. The
function takes the stack file data and decompresses it, producing the data of the originalstack file. You can open the output of the function directly as a stack.

The following statement opens a compressed stack file on a server:

go decompress(stack URL "http://www.example.net/comp.gz")

The statement automatically downloads the file "comp.gz", uncompresses it, and opensthe main stack of the file.

Saving stacks from a server

When a stack is downloaded using the go command, it's loaded into memory, but notsaved on a local disk. Such a stack behaves like a new (unsaved) stack until you use the
save command to save it as a stack file.

Note: Saving a stack that has been downloaded with the go command does not re-
upload it to its server. To upload a changed stack, you must save it to a local file, then use
one of the methods described in this topic to upload the file to the server.
 
11.6Other Internet Commands

The Internet library has a number of additional commands for working with web forms,
ftp commands, custom settings and troubleshooting. These commands are documented in
more detail the LiveCode Dictionary.

Launching the User's Browser with a URL

To launch the default browser with a URL, use the launch URL command.

launch URL "http://www.runrev.com/"

Note: To render web pages within LiveCode, instead of launching an external browser,
use the revBrowser. See the section on revBrowser for more information.
February 26, 2014, at 03:48 PM by Massimiliano Vessi -
Changed line 1774 from:
!!Trasferimenti in background
to:
!!Trasferimenti in background e copia cache
Changed lines 1785-1786 from:
Notate come potete impostare un messaggio che si attivi alla fine dello scaricamento; questo messaggio potrebbe far apparire una finestra o attivare altre funzioni del programma. Il comando '''load''' non salva l file in una variabile effettiva, ma copia la pagine o il file in una memoria comune in modo che non sia piu' necessario scaricarla, quindi per utilizzarla bisogna scrivere '''put''' come al solito:
to:
Notate come potete impostare un messaggio che si attivi alla fine dello scaricamento; questo messaggio potrebbe far apparire una finestra o attivare altre funzioni del programma. Il comando '''load''' non salva l file in una variabile effettiva, ma copia la pagine o il file in una memoria comune (''cache'') in modo che non sia piu' necessario scaricarla, quindi per utilizzarla bisogna scrivere '''put''' come al solito:
Changed lines 1790-1815 from:
come

11.5.1 Non-blocking transfers
When you transfer a file using URL containers, the file transfer stops the current handler
until the transfer is done. This kind of operation is called a blocking operation, since itblocks the current handler as long as it's going on.

If you want to transfer data using http without blocking, use the load command. if you
want to transfer large files using ftp, use the libURLftpUpload,
libURLftpUploadFile, or libURLDownloadToFile commands.

Non-blocking file transfers have several advantages:

Since contacting a server may take some time due to network lag, the pause involved in ablocking operation may be long enough to be noticeable to the user
. 

If a blocking operation involving a URL is going on, no other blocking operation can
start until the previous one is finished. If a
non-blocking file transfer is going on,
however, you can start other non-blocking file transfers. This means that if you use thelibrary commands, the user can begin multiple file transfers without errors.

During a non-blocking
file transfer, you can check and display the status of the transfer.
This lets you display the transfer's progress and allow the user to cancel the file transfer.

Using the load command

The load command downloads the specified document in the background and places itin a cache. Once a document has been cached, it can be accessed nearly instantaneously
when you use its URL, because LiveCode uses the cached copy in memory instead ofdownloading the URL again.

to:
come vedete apparentemente il codice sembra che carichi la pagina dentro la variabile ''var1'' come al solito, in realta' la pagina e' stata prima copiata in na memoria interna, in gergo ''copia cache'', e poi non ogni volta che viene richiamata viene presa la copia ''cache''. Il vantaggio e' duplice: potete richiamare la pagina anche cento volte senza doverla leggere dal sito ogni volta, potete inoltre mettere in ''cache'' tante pagine senza bloccare l'esecuzione del programma.

Usando il comando '''load''' potete anche sapere se ci sono stati problemi con lo scaricamento grazie alla proprieta' '''URLStatus''':

 load URL "http://www.example.com/index.html"
 put the URLStatus of  "http://www
.example.com/index.html" into esempioStatus

la proprieta' ''URLStatus'' puo' assumere i seguenti valori:

* queued - e' ancora nella lista delle pagine da scaricare
* contacted - il sito esiste, ma ancora
non la scaricato
* requested - il link e' stato richiesto
* loading, bytes, Totalbytes - sta ricevendo un file grosso , indica quanti byte ha ricevuto e quanto e' il totale di byte del
file
* uploading, bytes, bytesTotal -sta inviano un file, indica quanti byte ha inviato e quanto e' il totale di byte del file
* cached - la pagina e' nella cache e completo
* uploaded - il file e' stato caricato
* error - c'e' stato un errore e non e' stato trasferito
* timeout - errore di ''time out'', puo' essere dovuto a tanti fattori, anche ad una connessione troppo lenta
* empty -  e' stato elimanto dalla ''cache'' o non c'e'

Chiaramente non ha senso tenere impegnata la memoria ''cache'' se non avete piu' intenzione di leggere una determinata pagina o risorsa, per questo motivo potete cancellarla dalla ''cache'' o interrompere il suo scaricamento con il comando '''unload''':

  unload URL "http://www.example.com/index.html"


!!FTP con grossi file


Se i vostri file sono veramente grossi


libURLftpUpload uploads data to an FTP server

Deleted lines 1823-1859:
To use a file that has been downloaded by the load command, refer to it using the URLkeyword as usual. When you request the original URL, LiveCode uses the cached fileautomatically.

For best performance, use the load command at a time when response speed isn't critical(such as when your application is starting up), and only use it for documents that must bedisplayed quickly, such as images from the web that will be shown when you go to thenext card.

Checking status when using the load command

While a file is being transferred using the load commands, you can check the status of thetransfer using the URLStatus function. This function returns the current status of a
URL that's being downloaded or uploaded:

put the URLStatus of "ftp://ftp.example.com/myfile.txt" \
into field "Current Status"

The URLStatus function returns one of the following values:

queued - on hold until a previous request to the same site is completedcontacted - the site has been contacted but no data has been sent or received yet
requested - the URL has been requestedloading bytesTotal, bytesReceived - the URL data is being receiveduploading bytesTotal, bytesReceived - the file is being uploaded to the URL
cached - the URL is in the cache and the download is completeuploaded - the application has finished uploading the file to the URL
error - an error occurred and the URL was not transferred
timeout - the application timed out when attempting to transfer the URL

To monitor the progress of a file transfer or display a progress bar, you check theURLStatus function repeatedly during the transfer. The easiest way to do this is with
timer based messaging – see the section of the same name in the chapter Coding in
LiveCode, for more information.

Canceling a file transfer & emptying the cache

To cancel a transfer initiated with the load command and empty the cache, use theunload command.

unload URL "http://example.org/new_beta"

Uploading and downloading large files using FTP

The Internet library provides a number of commands for transferring larger files via FTPwithout blocking.

libURLftpUpload uploads data to an FTP server

 
Changed lines 1834-1837 from:
libURLftpUploadFile \
"test.data","ftp://ftp.example.org/test"
put URL "binfile:test.data" \
into URL "ftp://ftp.example.org/test"
to:
libURLftpUploadFile "test.data","ftp://ftp.example.org/test"
put URL "binfile:test.data" into URL "ftp://ftp.example.org/test"
February 26, 2014, at 02:24 PM by Massimiliano Vessi -
Changed lines 1743-1748 from:
to:
!!Cancellare

Per cancellare basta usare il comando '''delete''':

 delete URL "binfile:../mytext.txt"

Changed lines 1764-1765 from:
potete anche utilizzare il protocollo ftp:
to:
potete anche utilizzare il protocollo ''ftp'':
Changed lines 1768-1769 from:

to:
potete anche inviare file sia con protocollo ''http'' (la maggior parte dei server non lo permette), sia con protocollo ''ftp'':

 put "Testo di esempio" into URL "http://www.maxvessi.net/esempio.txt"
 put "Testo di esempio" into URL "ftp://user:password@ftp.maxvessi.net/esempio.txt"

Changed lines 1774-2094 from:
The http and ftp schemes designate documents or directories that are located on
another system that's accessible via the Internet. The file, binfile, and resfile
schemes designate local files.

11.4.3 The http scheme
An http URL designates a document from a web server:

put URL "http://www.example.org/home.htm" into field "Page"

When you use an http URL in an expression, LiveCode downloads the URL from theserver and substitutes the downloaded data for the URL.

When you put something into an http URL, LiveCode uploads the data to the web
server:

put field "Info" into URL "http://www.example.net/info.htm"

Note: Because most web servers do not allow HTTP uploads, putting something into anhttp URL usually will not be successful. Check with the server's administrator to find
out whether you can use the HTTP protocol to upload files.
For more details about http URLs, see the entry for the http keyword in the LiveCode
Dictionary.

11.4.4 The ftp scheme
An ftp URL designates a file or directory on an FTP server:

get URL "ftp://user:passwd@ftp.example.net/picture.jpg"

When you use an ftp URL in an expression, LiveCode downloads the URL from theserver and substitutes the downloaded data for the URL.

When you put something into an ftp URL, LiveCode uploads the data to the FTP
server:

put image 10 into \
URL "ftp://user:passwd@ftp.example.net/picture.jpg""

FTP servers require a user name and password, which you can specify in the URL. If you
don't specify a user name and password, LiveCode adds the "anonymous" user name and
a dummy password automatically, in accordance with the convention for public FTP
servers.

 
Note: Uploading to an FTP server usually requires a registered user name and password.
For more details about ftp URLs, see the entry for the ftp keyword in the LiveCode
Dictionary.

Directories on an FTP server

A URL that ends with a slash (/) designates a directory (rather than a file). An ftp URL
to a directory evaluates to a listing of the directory's contents.

11.4.5 The file scheme
A file URL designates a file on your system:

put field "Stuff" into URL "file:/Disk/Folder/testfile"

When you use a file URL in an expression, LiveCode gets the contents of the file you
designate and substitutes it for the URL. The following example puts the contents of afile into a variable:

put URL "file:myfile.txt" into myVariable
When you put data into a file URL, LiveCode puts the data into the file:
put myVariable into URL "file:/Volumes/Backup/data"


Note: As with local variables, if the file doesn't exist, putting data into it creates the file.
To create a URL from a file path that LiveCode provides, use the & operator:

answer file "Please choose a file to get:"
get URL ("file:" & it)

File path syntax and the file scheme:

The file URL scheme uses the same file path syntax used elsewhere in LiveCodestatements. You can use both absolute paths and relative paths in a file URL.

Conversion of end-of-line markers

Different operating systems use different characters to mark the end of a line. Mac OS Xuses a return character (ASCII 13), Unix systems use a linefeed character (ASCII 10),
and Windows systems use a return followed by a linefeed. To avoid problems when
transporting a stack between platforms, LiveCode always uses linefeeds internally when
you use a file URL as a container. LiveCode translates as needed between the your
system's end-of-line marker and LiveCode's linefeed character. To avoid this translation,
use the binfile scheme (see below).

 
11.4.6 The binfile scheme
A binfile URL designates a file on your system that contains binary data:

put URL "binfile:beachball.gif" into image "Beachball"

When you use a binfile URL in an expression, LiveCode gets the contents of the fileyou designate and substitutes it for the URL. The following example puts the contents ofa file into a variable:

put URL "binfile:picture.png" into pictVar

When you put data into a binfile URL, LiveCode puts the data into the file:

put pictVar into URL "binfile:/Volumes/Backup/pict.png"
put image 1 into "binfile:/image.png"

As with local variables, if the file doesn't exist, putting data into it creates the file.

Note: The binfilescheme works like the filescheme, except that LiveCode doesnot attempt to convert end-of-line markers. This is because return and linefeed characters
can be present in a binary file but not be intended to mark the end of the line. Changing
these characters can corrupt a binary file, so the binfilescheme leaves them alone.
11.4.7 The resfile scheme
On Mac OS Classic (and sometimes on OS X systems), files can consist of either a datafork or a resource fork or both.

Important: While LiveCode supports reading and writing resource fork files on Mac OS
X and Mac OS Classic, this feature is only intended to help you access and work withlegacy files. We do not generally recommend the use of resource forks when designing
any new application.
The resource fork contains defined resources such as icons, menu definitions, dialog
boxes, fonts, and so forth. A resfile URL designates the resource fork of a Mac OS or
OS X file:

put myBinaryData into URL "resfile:/Disk/Resources"

When you use a resfile URL in an expression, LiveCode gets the resource fork of thefile you designate and substitutes it for the URL.

 
When you put data into a resfile URL, LiveCode puts the data into the file's resource
fork.

Note: A resfile URL specifies the entire resource fork, not just one resource. To
work with individual resources, use the getResource, setResource,
deleteResourceand copyResource functions.
The most common use for this URL scheme is to copy an entire resource fork from onefile to another. To modify the data from a resfile URL, you need to understand the
details of Apple's resource fork format.

Creating a resource fork

Unlike the file and binfile URL schemes, the resfile keyword cannot be used
to create a file. If the file doesn't yet exist, you cannot use the resfile keyword to create it.
To create a new resource file, first use a file URL to create the file with an empty
data fork, then write the needed data to its resource fork:

put empty into URL "file:myFile" -- creates an empty fileput myStoredResources into URL "resfile:myFile"

11.4.8 Manipulating URL contents
You use a URL like any other container. You can get the content of a URL or use itscontent in any expression. You can also put any data into a URL.

http, ftp, binfile, and resfile URLs can hold binary data.

http, ftp, and file URLs can hold text.

The URL keyword

To specify a URL container, you use the URL keyword before the URL, which can use
any of the five schemes described above:

if URL "http://www.example.net/index.html" is not empty...
get URL "binfile:/Applications/Hover.app/data"
put 1+1 into URL "file:output.txt"

The URL keyword tells LiveCode that you are using the URL as a container.

Note: Some properties (such as the filename of a player or image) let you specify a
URL as the property's value. Be careful not to include the URL keyword when specifying
such properties, because using the URLkeyword indicates that you're treating the URL asa container. If you use the URL keyword when specifying such a property, the property is
set to the contents of the URL, not the URL itself, and this is usually not what's wanted.
 
Using the content of a URL

As with other containers, you use the content of a URL by using a reference to the URLin an expression. LiveCode substitutes the URL's content for the reference.

If the URL scheme refers to a local file (file, binfile, or resfile URLs),
LiveCode reads the content of the file and substitutes it for the URL reference in the
expression:

answer URL "file:../My File" -- displays the file's contentput URL "binfile:flowers.jpg" into myVariableput URL "resfile:Icons" into URL "resfile:New Icons"

If the URL scheme refers to a document on another system (httpor ftp URLs),
LiveCode downloads the URL automatically, substituting the downloaded data for theURL reference:

answer URL "http://www.example.net/files/greeting.txt"

Note: If the server sends back an error message--for example, if the file you specify in
an http URL doesn't exist--then the error message replaces the URL reference in the
expression.
Important: When you use an ftpor httpURL in an expression, the handler pausesuntil LiveCode is finished downloading the URL. If you do not want to block LiveCode
when accessing these resources, use the load URL form of the command (see below).
Putting data into a URL

As with other containers, you can put data into a URL. The result of doing so depends on
whether the URL scheme specifies a file on your system (file, binfile, or
resfile) or on another system (httpor ftp).

If the URL scheme refers to a local file (file, binfile, or resfile URLs),
LiveCode puts the data into the specified file:

put field "My Text" into URL "file:storedtext.txt"
put image 1 into URL "binfile:picture.png"

If the URL scheme refers to a document on the Internet (httpor ftp URLs), LiveCode
uploads the data to the URL:

put myVar into URL "ftp://me:pass@ftp.example.net/file.dat"

 
Note: Because most web servers do not allow HTTP uploads, this usually will not besuccessful with the httpscheme.
Chunk expressions and URLs

Like other containers, URLs can be used with chunk expressions to specify a portion ofwhat's in a URL--a line, an item, a word, or a character. In this way, any chunk of a URLis like a container itself. For more information about Chunk Expressions, see the chapter
on Processing Text and Data.

You can use any chunk of a URL in an expression, in the same way you use a wholeURL:

get line 2 of URL "http://www.example.net/index.html"
put word 8 of URL "file:/Disk/Folder/myfile" into field 4if char 1 of URL "ftp://ftp.example.org/test.jpg" is "0"...

You can also specify ranges, and even one chunk inside another:

put char 1 to 30 of URL "binfile:/marks.dat" into myVaranswer line 1 to 3 of URL "http://www.example.com/file"

Putting data into a chunk

If the URL is local (that is, if it is a file, binfile, or resfile URL), you can put a
value into a chunk of the URL:

put it into char 7 of URL "binfile:/picture.gif"
put return after word 25 of URL "file:../datafile"
put field 3 into line 20 of URL "file:myfile.txt"

You can also put a value into a chunk of an ftpor http URL. Because it's impossibleto upload part of a file, LiveCode downloads the file, makes the change, then uploads thefile back to the server.

Tip: This method is inefficient if you need to make several changes. In this case, it's
faster to first put the URL in a variable, replace the chunk you want to change, then put
the variable into the URL:
put URL "ftp://me:secret@ftp.example.net/file.txt" into \

myVarput field "New Info" after line 7 of myVarput field "More" into word 22 of line 3 of myVarput myVar into URL \

"ftp://me:secret@ftp.example.net/file.txt"

 
This ensures that the file only needs to be downloaded once and re-uploaded once, no
matter how many changes you need to make.

11.4.9 URLs and memory
URLs, unlike other containers, are only read into memory when you use the URL in astatement. Other containers – like variables, fields, buttons, and images – are normally
kept in memory, so accessing them doesn't increase memory usage.

This means that in order to read a URL or place a value in a chunk of a URL, LiveCodereads the entire file into memory. Because of this, you should be cautious when using aURL to refer to any very large file.

Even when referring to a single chunk in a URL, LiveCode must place the entire URL in
memory. An expression such as line 347882 of URL "file:bigfile.txt"
may be evaluated very slowly or even not work at all, if insufficient memory is available.
If you refer to a chunk of an ftpor http URL, LiveCode must download the entire file
to find the chunk you specify.

Tip: If you need to read and write large quantities of data to a file, or seek
through the contents of a large file without loading the entire contents into memory, use
the open file, read from file, seekand close filecommands instead of
the URL commands. For more information on these commands see the LiveCode
Dictionary.
11.4.10 Deleting URLs
You remove a URL with the delete URL command.
To delete a local file, you use a fileor binfile URL:


delete URL "file:C:/My Programs/test.exe"
delete URL "binfile:../mytext.txt"

It doesn't matter whether the file contains binary data or text; for deletion, these URLschemes are equivalent.

Tip: You can also use the delete file command to remove a file.

To delete the resource fork of a file, you use a resfile URL. The following exampleremoves the resource fork along with all resources, but leaves the file in place:

delete URL "resfile:/Volumes/Backup/proj.rev"

 
Tip: To delete a single resource instead of the entire resource fork, use thedeleteResource function.
To remove a file or directory from an FTP server, you use an ftp URL:

delete URL "ftp://root:secret@ftp.example.org/deleteme.txt"
delete URL "ftp://me:mine@ftp.example.net/trash/"

As with creating files, you can use an http URL to delete a file, but most HTTP servers
are not configured to allow this.

11.5Uploading and Downloading Files

The simplest way to transfer data to an FTP or HTTP server is to use the put command
to upload, or use the URL in an expression to download.

The Internet library includes additional commands to upload and download files to and
from an FTP server. These commands offer more versatile options for monitoring and
controlling the progress of the file transfer.

Uploading using the put command

As mentioned above, putting something into an ftp or http URL uploads the data to
the server:

put myVariable \
into URL "ftp://user:pass@ftp.example.org/newfile.txt"

If you use the put command with a fileor binfile URL as the source, the file is
uploaded:

put URL "file:newfile.txt" \
into URL "ftp://user:pass@ftp.example.org/newfile.txt"

When you upload data in this way, the operation is blocking: that is, the handler pausesuntil the upload is finished. (See below for details on how to create a file transfer that isnot blocking.) If there is an error, the error is placed in the result function:

put field "Data" into URL myFTPDestinationif the result is not empty then beep 2

Important: Uploading or downloading a URL does not prevent other messages frombeing sent during the file transfer: the current handler is blocked, but other handlers are
not. For example, the user might click a button that uploads or downloads another URL
 
while the first URL is still being uploaded. In this case, the second file transfer is notperformed and the result is set to "Error Previous request has not completed." To
avoid this problem, you can set a flag while a URL is being uploaded, and check that flag
when trying to upload or download URLs to make sure that there is not already a filetransfer in progress.
Downloading using a URL

Referring to an ftpor http URL in an expression downloads the document.

put URL "ftp://ftp.example.net/myfile.jpg" into image 1get URL "http://www.example.com/newstuff/newfile.html"

If you use the put command with a fileor binfile URL as the destination, the
document is downloaded to the file:

put URL "ftp://ftp.example.net/myfile.jpg" \
into URL "binfile:/Disk/Folder/myfile.jpg"
to:
!!Trasferimenti in background
Potete mettere a scaricare uno o piu' file senza bloccare il programma in attesa di aver scaricato tutti i file. Un altro vantaggio e' la possibilita' di poter vedere lo stato di avanzamento di uno scaricamento.

Il comando per scaricare e' '''load''':

 load URL "http://www.example.com/index.html"
 load URL "http://www.example.com/test.html" with message "myUrlDownloadFinished"
 on myUrlDownloadFinished
  answer "Scaricamento finito" with "OK"
 end myUrlDownloadFinished

Notate come potete impostare un messaggio che si attivi alla fine dello scaricamento; questo messaggio potrebbe far apparire una finestra o attivare altre funzioni del programma. Il comando '''load''' non salva l file in una variabile effettiva, ma copia la pagine o il file in una memoria comune in modo che non sia piu' necessario scaricarla, quindi per utilizzarla bisogna scrivere '''put''' come al solito:

  load URL "http://www.example.com/index.html"
  put URL "http://www.example.com/index.html" into var1

come

11.5.1 Non-blocking transfers
When you transfer a file using URL containers, the file transfer stops the current handler
until the transfer is done. This kind of operation is called a blocking operation, since itblocks the current handler as long as it's going on.

If you want to transfer data using http without blocking, use the load command. if you
want to transfer large files using ftp, use the libURLftpUpload,
libURLftpUploadFile, or libURLDownloadToFile commands.

Non-blocking file transfers have several advantages:

Since contacting a server may take some time due to network lag, the pause involved in ablocking operation may be long enough to be noticeable to the user.

If a blocking operation involving a URL is going on, no other blocking operation can
start until the previous one is finished. If a non-blocking file transfer is going on,
however, you can start other non-blocking file transfers. This means that if you use thelibrary commands, the user can begin multiple file transfers without errors.

During a non-blocking file transfer, you can check and display the status of the transfer.
This lets you display the transfer's progress and allow the user to cancel the file transfer.

Using the load command

The load command downloads the specified document in the background and places itin a cache. Once a document has been cached, it can be accessed nearly instantaneously
when you use its URL, because LiveCode uses the cached copy in memory instead ofdownloading the URL again.

February 26, 2014, at 12:41 PM by Massimiliano Vessi -
Changed lines 1712-1714 from:
 
! Inviare e ricevere informazioni con files, internet e i sockets

to:

Changed lines 1753-1777 from:

11.4Working with URLs

A
URL is a container for a file (or other resource), which may either be on the samesystem the application is running on, or on another system that's accessible via the
Internet
. 

This topic discusses the various URL schemes that LiveCode implements, how to createand manipulate files using URLs, and how to transfer data between your system and an
FTP or HTTP server.

To fully understand this topic, you should know how to create objects and write shortscripts, and understand how to use variables to hold data. You should also have a basicunderstanding of how the Internet works.

11.4.1 An Overview of URLs
In the LiveCode language, a URL is a container for a file or other document, such as theoutput of a CGI on a web server. The data in a URL may be on the same system theapplication is running on, or may be on another system.

URLs in LiveCode are written like the URLs you see in a browser. You use the URL
keyword to designate a URL, enclosing the URL's name in double quotes:

put field "Info" into URL "file:myfile.txt"
get URL "http://www.example.org/stuff/nonsense.html"
put URL "ftp://ftp.example.net/myfile" into field "Data"

11.4.2 URL Schemes
A URL scheme is a type of URL. LiveCode supports five URL schemes with the URL
keyword: http, ftp, file, binfile, and (for backwards compatibility on Mac OS
Classic and OS X) resfile.
to:
!Internet

Utilizzando la parola '''
URL''' potete interagire su internet, per esempio se volete leggere il contenuto di una pagina potete scrivere:

 put URL "http://www.maxvessi.net/pmwiki/pmwiki.php" into miaVar

potete anche utilizzare il protocollo ftp:

 put URL "ftp://www
.maxvessi.net/esempio.pdf" into miaVar

February 24, 2014, at 05:12 PM by Massimiliano Vessi -
Deleted lines 1753-1866:

If your application creates files with your application's creator signature, you should
include in your application's plist an entry for each file type you use. Once you have builtyour standalone application, follow these steps to open the plist file:

1. Right click on your application bundle, navigate to the contents folder and open the"Info.plist" file. If you have installed Apple's developer tools, you have an application
called "Property List Editor", which you can use to make changes to the plist file.
Otherwise, you can edit the file in a text editor.
2. Locate the information for the document type. In Property List Editor, expand the"Root" node, then expand the "CFBundleDocumentTypes" node, then expand the "0"
node. In a text editor, locate "CFBundleDocumentTypes". Below it, note the tags"<array>" and "<dict>". The information for the first document type is between "<dict>"
and "</dict>".
3. Enter the file description, which is a short phrase describing what kind of file this is. In
Property List Editor, change the value of "CFBundleTypeName" to the description you
want to use. In a text editor, locate "CFBundleTypeName" in the document information.
Below it is the file description, enclosed between "<string>" and "</string>":
<string>LiveCode Stack</string>
Change the description to the one you want to use.

Important: Do not change the tags (enclosed in "<" and ">"). Only change what's
between them.
4. Enter the file extension. In Property List Editor, expand "CFBundleTypeExtensions"
and enter the file extension in the "0" node. In a text editor, locate"CFBundleTypeExtensions" in the document information. Below it is the extension,
enclosed in "<array>" and "<string>" tags. Change the extension to the one you want to
use.
5. Enter the four-character file type. In Property List Editor, expand
"CFBundleTypeOSTypes" and enter the file type in the "0" node. In a text editor, locate"CFBundleTypeOSTypes" in the document information. Below it is the file type,
enclosed in "<array>" and "<string>" tags. Change the file type to the one you want to
use.
If the format for this type of file is standard (such as plain text), use a standard type (such
as "TEXT"). If the format belongs to your application, use a custom file type of your
choice.

 
Important: Apple reserves all file types with no uppercase letters. If you use a customfile type for your application, make sure it contains at least one uppercase letter.
If you want to assign more file types to your application, copy the portion of the plist fileinside the "CFBundleTypes" array between "<dict>" and "</dict>", including these tags.
The "CFBundleTypes" node should now contain two "<dict>" nodes and all their
contents. Repeat the steps above for each different file type your application can create.

Creating Files

When your application creates files, set the fileType property to the desired creator
signature and file type for the new file. (For stack files created with the save command,
use the stackFileType property instead.) When creating files, the application uses
the current value of the fileTypeor stackFileType property to determine what
creator and file type the new file should have.

It's important to understand that a file's creator signature determines which application islaunched automatically when you double-click the file, but doesn't prevent other
applications from being able to open that file. For example, if your application createsfiles of type "TEXT", any text editor can open the files. If your application creates stack
files, and uses the file type "RSTK", then LiveCode will be able to open the stack files, aswell as your application.

File extensions

You can add an extension to the name of any OS X file. When the user double-clicks afile with no creator signature, the operating system uses the extension to determine which
application to use to open the file.

An application bundle's name should end with the extension ".app".

Note: Apple's recommendations for determining file type and creator on OS X systemsare currently in flux. The recommended method for the present is to set a file type and
creator signature, and also attach an extension to the end of each file's name when it is
created. Valid extensions on OS X systems are up to twelve characters in length, and
may include the letters a-z, the digits 0-9, $, %, _, or ~. For up-to-date information on
Apple's recommendations for OS X, see Apple's developer documentation at
<http://www.apple.com/developer/>.
11.3.3 Mac OS Classic File Types and Creators
When a file is saved on a Mac OS system, a four-character creator signature is saved with
it. The creator signature specifies which application owns the file. Every Mac OS and OSX application should have a unique creator signature. (Apple maintains a registry ofcreator signatures on its web site at <http://developer.apple.com/dev/cftype/>.)

 
Mac OS files have a separate file type, also four characters long, which specifies theformat of the file. The file type is also used to determine which applications (other than
the owner) can work with the file. The file type of all applications is "APPL".

Applications that don't own files

To assign your unique creator signature when building an application, enter the signatureon the Mac OS screen of the Standalone Application Settings window. LiveCodeautomatically includes the resources needed for Mac OS to recognize the creator
signature.

Applications that own their own files

If your application creates files with your application's creator signature, you should
include in your application a set of resources for each file type you use. Once you havesaved your standalone application, open the application file in ResEdit and follow thesesteps:

1. Open the BNDL resource window, then open the BNDL 128 resource. The BNDL 128
resource contains a single entry ("APPL").
2. Choose "Create New File Type" from the Resources menu. A new entry appears belowthe "APPL" entry.
3. In the Type field, enter the four-character file type. If the format for this type of file isstandard (such as plain text), use a standard type (such as "TEXT"). If the format belongsto your application, use a custom file type of your choice.
Repeat steps 2-3 for each different file type your application can create.

When your application creates files, set the fileType property to the desired creator
signature and file type for the new file. For stack files created with the save command,
use the stackFileType property instead. When creating files, the application uses the
current value of the fileTypeor stackFileType property to determine what
creator and file type the new file should have.

Installing custom icons

Each Mac OS file may display any of six different icons, depending on context and on
the number of colors the screen can display: large (32x32 pixel) icons and small (16x16
pixel) icons, each in black-and-white, 16 colors, and 256 colors.

Mac OS provides default icons that are used for applications and documents that don'thave their own. If you want your application or the documents it owns to display acustom icon, you must create the icons and then attach them to the application.

Custom application icons

 
If you want to include a custom icon for your application, use ResEdit or a similar tool to
create a set of icon resources. There are six standard icon resource types: ICN# (blackand-
white), icl4 (four-bit color), icl8 (8-bit color), ics# (black-and-white small), ics4 (4bit
small), and ics8 (8-bit small). Each of these application icons should have the resourceID 128.

Save the icons in a single file, and use the "Include resources from file" option on theMac OS screen of the Standalone Application Settings window to specify the file. When
you build the application, the icons will be included in the application's file.

11.3.4 Unix File Extensions
Unix systems do not have an overall required method for specifying a file's type, butmost files on a Unix system are created with extensions in the file name, similar to theextensions used on Windows systems. These extensions may be of any length and may
include any characters (other than /).
February 24, 2014, at 04:42 PM by Massimiliano Vessi -
Added lines 1735-1736:
'''NOTA:''' per chi usa il Mac c'e' e ci sara sempre un problema con i nomi, perche' il Mac permette di usare il simbolo "/" (slash) per i nomi dei files, ma questo crea sempre molta ambiguita' sui percorsi. Livecode cerca di superarla sostituendo automaticamente il carattere "/" con i due punti ":".  Siccome il due punti sono vietati su Mac, l'ambiguita' e' risolta. Comunque evitate di usare il carattere slash (/)con i nomi, crea solo confusione.
Changed lines 1745-1750 from:

Similarly, when dealing with a bundle, use the delete folder command instead of
delete file, and the revCopyFolder command instead of revCopyFile.

Referring to files inside a bundle

to:
!!Cartelle speciali

Livecode utilizza delle scorciatoie per delle cartelle predefinite, esempi:

 put specialFolderPath("Desktop") into myPath
 put specialFolderPath("Start") into myPath
 put the DefaultFolder into myPath

Deleted lines 1753-1970:
When referring to a file that's inside a bundle, you can treat the bundle just as if it were afolder. For example, if you have placed a file called "My Support.txt" inside your
application's bundle, the absolute path to the file might look like this:

/Volumes/Disk/Applications/MyApp/My Support.txt

The / character in a file or folder name

The slash (/) is not a legal character in Unix or Windows file or folder names, but it islegal for Mac OS file or folder names to contain a slash. Since a slash in a file or folder
name would cause ambiguity – is the slash part of a name, or does it separate one level ofthe hierarchy from the next? – LiveCode substitutes a colon (:) for any slashes in folder
or file names on Mac OS systems.

For example, if a file on a Mac OS system is named "Notes from 12/21/93", you refer to
it in a script as "Notes from 12:21:93". Since the colon is not a legal character in Mac OSfolder or file names, this removes the ambiguity.

11.1.2 Absolute and Relative File Paths
When describing how to get to a file, you have two options. You can start from the top
level, the name of the disk, and name each of the enclosing folders until you get to thefile. This is called an absolute path, because it's independent of where you start from. Or
you can start from the current folder and describe how to get to the file from there. This iscalled a relative path, because it depends on where you start.

All the file paths shown so far in this topic are absolute paths.

Absolute file paths

Absolute file paths do not depend on which folder your stack file is in or on where thecurrent folder is. An absolute path to a particular folder or file is always written the same
way.

For example, suppose your application is in a folder called "Application Folder", and you
want to specify a file called "Westwind" which is in a folder called "Stories" inside"Application Folder".

Hard Disk

Top Folder

My Folder

My File

Application Folder

My Application

Stories

Westwind

The absolute file path of your application looks like this:
/Hard Disk/Application Folder/My Application

 
and the absolute path of the "Westwind" file looks like this:
/Hard Disk/Application Folder/Stories/Westwind

Note: On Mac OS, OS X, and Unix systems, absolute file paths always start with a slash
character. On Windows systems, absolute file paths always start with a drive letter
followed by a colon (:).
Relative file paths

Now suppose you want to tell someone how to get to the "Westwind" file, starting fromthe folder containing the application.

Since the application is in "Application Folder", we don't need to include the steps to getto "Application Folder". Instead, we can describe the location of the "Westwind" file with
this relative pathname:

Stories/Westwind

This relative pathname starts at "Application Folder"--the folder that holds theapplication--and describes how to get to the "Westwind" file from there: you open thefolder "Stories", then find "Westwind" inside it.

A relative file path starts at a particular folder, rather than at the top of the file system likean absolute file path. The relative file path builds a file path from the starting folder to thefile or folder whose location is being specified.

Finding the current folder

By default, the current folder is set to the folder containing the application (either theLiveCode development environment or your application, depending on whether your
application is a standalone). So in the example above, the current folder is "Application
Folder", because that's where the running application is located.

Note: To change the current folder, set the defaultFolderproperty.
Going up to the parent folder

The relative path ".." indicates the current folder's parent folder. If the current folder is"Stories", the relative path

 ..
means the same thing as the absolute path

/Hard Disk/Application Folder/

Going up multiple levels

To go up more than one level, use more than one "../". To go up two levels, use "../../"; to
go up three levels, use "../../../", and so forth.

 
For example, suppose the current folder is "Stories", and its absolute path looks like this:

/Hard Disk/Application Folder/Stories/

To get to "My Application" in "Application Folder", you go up one level to "Application
Folder", then down one level to "My Application". The relative path looks like this:

../My Application

To get to "Top Folder" on "Hard Disk", you go up two levels--to "Application Folder",
then to "Hard Disk"--and then down one level to "Top Folder". The relative path lookslike this:

 ../../Top Folder/

Starting at the home directory

On OS X and Unix systems, the "~" character designates a user's home directory.

A path that starts with "~/" is a relative path starting with the current user's homedirectory. A path that starts with "~", followed by the user ID of a user on that system, isa relative path starting with that user's home directory.

11.1.3 When to use relative and absolute file paths
Absolute file paths and relative file paths are interchangeable. Which one to use dependson a couple of factors.

Absolute file paths are easy to understand and they don't change depending on the currentfolder. This can be an advantage if you are changing the defaultFolder regularly.

However absolute file paths always include the full name of the hard disk and foldersleading up to the current working folder. Therefore, if you plan to distribute your
application you will want to work with relative paths, so that media shipped in subfolderswith your application is still easy to locate.

Tip: By default, when linking to an image or resource using the Inspector, LiveCode
inserts an absolute file path. If you plan to distribute your application, locate your media
in a subfolder next to the stack you are working on and convert these file paths to relative
file paths by deleting the directories up to the one you are working in. This will mean youdon't need to make any changes when it comes time to distribute your application.
It's OK to use absolute paths to specify files or folders that the user selects after
installation. For example, if you ask the user to select a file (using the answer file
command) and read data from the file, there's no need to convert the absolute path that
the answer file command provides to a relative path. Because you're using the path
right after you get it from the answer command, you know that the disk name and
folder structure aren't going to change between getting the path and using it.

 
11.2Special Folders

Modern operating systems each have a set of special-purpose folders designated for avariety of purposes. If you are writing an application it is recommended that you makeuse of these folders where appropriate so that you provide the best possible user
experience. For example, the contents of the desktop reside in a special folder; there is afolder set aside for fonts; there is a folder for application preferences; and so on.

These special folders don't always have the same name and location, so you can't rely on
a stored file path to locate them. For example, if your application is installed onto an OSlocalized into a different language, the names of the file path will be different, on someWindows special folders are named or placed differently depending on what version ofWindows is running, etc.

To find out the name and location of a special folder, regardless of any of these factors,
you use the specialFolderPath function. The function supports a number of formsfor each operating system, describing the special folders for each one. Some of the formsare the same cross-platform. The following example will get the location of the Desktop
folder on Windows, Mac OS X or Linux:

put specialFolderPath("Desktop") into myPath

To get the path to the Start menu's folder on a Windows system:

put specialFolderPath("Start") into myPath

For a complete list of possible folders see the, specialFolderPath in the LiveCode
Dictionary.

11.3File Types, Application Signatures & File Ownership

When you double-click a document file, it automatically opens in the application it's
associated with. Each operating system has a different method for associating files with
an application. In order to create files that belong to your standalone application, you
need to set up the association appropriately for each platform you distribute on.

This topic describes how to correctly associate your application with the files it creates.

11.3.1 Windows File Extensions and Ownership
When a file is saved on a Windows system, a three-character extension is usually added
to the file's name. The extension specifies the format of the file.

To determine which application to launch when the user double-clicks a file, Windowschecks the Windows registry to find out what application has registered itself as owning
the file's extension. Each application can add keys to the registry to identify certain fileextensions as belonging to it.

 
Applications that don't own files

If your application does not create files that you want the application to own, you don'tneed to make any modifications to the registry or specify any extensions.

Applications that own their own files

If your application creates files with its own custom extension, when you install theapplication, you should make changes to the Windows registry to identify the extension
as belonging to your application.

Popular Windows installer programs will make these registry changes automatically for
you. You can also perform these registry changes using the setRegistry function.

Installing custom icons

Each Windows file can display its own icon. You can have separate icons for your
application and for files it owns. Icon files must be stored in .ico format.

Custom application icons

If you want to include a custom icon for your application, use the "Application Icon"
option on the Windows screen of the Standalone Application Settings window to specify
the icon file. When you build the application, the icon will be included in the application.
For more information, see the chapter on Deploying Your Application.

Custom file icons

To include a custom icon for your documents, use the "Document Icon" option on theWindows screen of the Standalone Application Settings window to specify the icon file.
When you build the application, the icon will be included in the application.

Important: For the correct icon to appear on files your application creates, the file'sextension must be registered in the Windows registry.
File extensions

You can add an extension to the name of any Windows file. The extension may contain
letters A-Z, digits 0-9, ' (single quote), !, @, #, $, %, ^, &, (, ), -, _, {, }, `, or ~.

The Windows registry associates applications with the extension for the files they own.

11.3.2 OS X File Types and Creators
On OS X each file has a file extension which determines which application owns it.
However OS X systems can also use the unique four-character creator signature and afour-character file type used on Mac OS Classic (see below for more information).

OS X applications store file association information in a property list file, or plist. Each
application's plist is stored as part of its application bundle.

 
Applications that don't own files

To assign your unique creator signature when building an application, enter the signatureon the OS X screen of the Standalone Application Settings window. LiveCodeautomatically includes the creator signature in the application's plist.

Applications that own their own files
February 24, 2014, at 02:02 PM by Massimiliano Vessi -
Changed lines 1715-1716 from:
!!Scrivere o leggere un file
to:
!Scrivere o leggere un file
Changed lines 1725-1837 from:


11.1File Name Specifications and File Paths

A file path is a way of describing the location of a file or folder so that it can be found by
a handler. File paths are used throughout LiveCode: when you read to and write from textfiles, when you reference an external QuickTime file to display in a player, and in many
other situations. If your application refers to external files in any way, an understanding
of file path is essential.

This topic discusses the syntax for creating and reading a file reference, and how to relatefile paths to the location of your application so that they'll be accessible when your
application is installed on another system with a different folder structure.

11.1.1 What is a File Path?
A file path is a description of the exact location of a file or folder. The file path is created
by starting at the top of the computer's file system, naming the disk or volume that thefile is on, then naming every folder that encloses the file, in descending order, until thefile is reached.

Locating a file

For example, suppose you want to describe the location of a file called "My File", which
is located inside a folder called "My Folder". That folder is in turn located inside a folder
called "Top Folder", which is on a drive called "Hard Disk". You need all thisinformation to completely describe where the file is:

Hard Disk
Top Folder
My Folder
My File


If someone tells you which disk the file is on, then which folder to open, and so on, you
can find the file by opening each successive icon on your computer's desktop. By starting
with the disk, then opening each enclosing folder in succession until you arrive at the file,
you can find exactly the file that's being described.

The structure of a file path

A file path specifies each level of the hierarchy that encloses the file. LiveCode presentsthe information in a file path that might look like this:

/Hard Disk/Top Folder/My Folder/My File

You can see that to write a file path, you start by naming the disk the file is on, then add
each enclosing folder in order until you arrive at the file.

 
Tip: To see the path to a file, enter the following in the message box:
answer file "Choose a file:"; put it
This displays the file path for the file you choose.

Important: Each platform has its own way for programmers to specify file paths. The
file path shown above is in the usual style for file paths on Unix systems. For cross-
platform compatibility, LiveCode uses this same forward slash / character in its file path
regardless of the current platform. This way, you can generally specify file and work
with paths in your scripts without having to convert them when you switch platforms.
File paths on Windows systems

On Windows systems, disks are named with a drive letter followed by a colon character
(:). A typical LiveCode file path on a Windows system looks like this:

C:/folder/file.txt

File paths on OS X systems

On OS X systems, the startup disk, rather than the desktop, is used as the top level of thefolder structure. This means that the startup disk's name does not appear in file paths.
Instead, the first part of the file path is the top-level folder that the file is in.

If the disk "Hard Disk" is the startup disk, a typical path on OS X systems might look likethis:

 /Top Folder/My Folder/My File

Notice that the disk name isn't part of this path.

Note: If you need to find out the startup disk's name, check the first disk name returned
by the volumes function.
For files on a disk that isn't the startup disk, the file path starts with "/Volumes" instead of"/". A typical file path to a file that's on a non-startup disk on an OS X system looks like
this:

 /Volumes/Swap Disk/Folder/file.txt

Folder paths

 
You construct the path of a folder the same way as the path to a file. A folder path alwaysends with a slash character (/). This final slash indicates that the path is to a folder rather
than a file.

For example, this pathname describes a folder called "Project" inside a folder called
"Forbin" on a disk named "Doomsday":

/Doomsday/Forbin/Project/

If "Project" is a file, its pathname looks like this, without the final slash:

/Doomsday/Forbin/Project

File paths for OS X bundles

A bundle is a special type of folder, used on OS X, that is presented to the user as a singlefile but that is maintained internally by the operating system as a folder. Many OS Xapplications – including LiveCode and the applications it creates – are stored and
distributed as bundles that contain several files. When the user double-clicks the bundle
the application starts up instead of a folder window opening to show the bundle's
contents.

You can take advantage of the bundle concept to include any needed support files with
your application. If you place the files in the application's bundle, users ordinarily never
see them, and the entire application--support files and all--behaves as a single icon.

Tip: To see the contents of a bundle, right-click (or control click) the bundle and choose
"Show Package Contents" from the contextual menu.
Most of the time, the distinction between bundles and files doesn't matter. However werecommend that you treat them as files when working from the perspective of a user butotherwise refer to them as folders when coding. This will help to keep your codereadable. Thus if you are selecting a bundle in a file dialog use the answer file form.
When moving or renaming a bundle, refer to them as a folder.

Moving, renaming, or deleting a bundleWhen using the rename command, to rename a bundle, use the rename folder
form of the command:

 rename folder "/Volumes/Disk/Applications/MyApp/" \
to "/Volumes/Disk/Applications/OtherApp/"
to:
per savare basta usare '''put''' e '''URL''' insieme:

 put  "testo di esempio" into URL "binfile:esempio.txt"

potete usare put sia per testi che per file binari, ricordate sempre scrivere ''binfile:'' prima del nome del file.

Allo stesso modo potete leggere i file:

 put  URL "binfile:esempio.txt" into esempio

!!Rinominare

Per rinominare, basta utilizzare il comando '''rename''':

 rename "esempio.txt" to "esempio2.txt"
 rename folder "/Volumes/Disk/Applications/MyApp/" to "/Volumes/Disk/Applications/OtherApp/"



Similarly, when dealing with a bundle, use the delete folder command instead of
delete file, and the revCopyFolder command instead of revCopyFile.

Referring to files inside a bundle

February 24, 2014, at 12:20 PM by Massimiliano Vessi -
Changed lines 1713-1741 from:





 
 

 
Chapter 11 Transferring Information with Files, theInternet and Sockets

Reading and writing data to files or transferring data over the Internet are importantfunctions in most applications. LiveCode provides a rich feature set for performing theseoperations.

Accessing data from a file typically takes just a single line of code. LiveCode's file path
syntax uses the same format on each platform so you typically don't have to rewrite your
file handling routines to deploy cross platform. A
set of functions provides for copying,
deleting or renaming files, as well as accessing appropriate system and user folders.

LiveCode includes functions for downloading and uploading data to the Internet. Simpledownloads and uploads can be performed with just a single line of code. Support for thehttp, ftp and post protocols is included. Syntax is included that allows downloading in
both the foreground and background. Additional library commands allow you to
construct multipart form data, send ftp commands and more.

LiveCode includes built-in support for https, SSL & encryption.

If the built-in protocol support doesn't do what you need, LiveCode also allows you to
implement your own Internet protocols using its straightforward socket support. A very
basic client server application can be written in a few lines of code.

 
to:
! Inviare e ricevere informazioni con files, internet e i sockets

!!Scrivere o leggere un file

Quandi indicate un file o una directory, potete utilizzare sia un percorso relativo,che un percorso assoluto. Quando usate un percorso relativo, esso parte dalla cartella '''DefaultFolder'''; quindi se non sapete qual è questa cartella sul sistema operativo corrente, vi conviene impostarlo come la cartella del vostro eseguibile con il seguente codice:

 On OpenStack
  set itemDel to "/" 
 
set the defaultFolder to item 1 to -2 of (the effective fileName of this stack)
 end OpenStack



Added lines 3873-3874:
*SSL
*https
February 21, 2014, at 01:02 PM by Massimiliano Vessi -
Deleted lines 1719-2069:
Chapter 10 Error Handling & Debugging

In an ideal world everyone would write perfect code and there would never be any need
to debug. However in reality, virtually every project is going to require some degree ofdebugging. The more complex the project the more like this is to be true. Fortunately
LiveCode includes a full plethora of debugging tools and techniques that make it quick
and easy to track down errors. The live run-edit cycle allows you to see the effect ofcorrections as soon as you make them. And, unlike working in a lower-level language,
when you make a mistake you will receive a human-friendly error message pointing you
to where the error occurred, instead of the application unexpectedly quitting.

As well as the set of built-in error reporting and debugging tools, LiveCode also allowsyou complete flexibility over error handling, allowing you to provide a customized
experience to the end user of your application.

 
10.1Common Techniques for Solving Problems

If you encounter a problem with your code, there are a number of methods available to
help you track it down. In this section we detail some of the main techniques you may
find useful.

10.1.1 The LiveCode Error Dialog
Often the first thing that will alert you to a problem is an error dialog.


Figure 79 – An Error Dialog

There are two possible types of error dialog. The first is the Execution Error dialog. This
dialog is displayed when your script is running and encounters an error.

In the example above, the script was attempting to access field 100. This field does notexist. When LiveCode encounters a problem like this, execution will halt and the dialog
above will be displayed.

If you know what the error is from looking at it, use the Script button to go directly to thescript and edit it. The line that generated the error will be highlighted in the scriptwindow.

Alternatively, if you need more information the Debug button will load the script in thedebugger at the line the error occurred (see below for more information on using theDebugger). You can then load the Variable Watcher (see below) to see the state of all thevariables at the point where execution was halted.

 
Note: The Debug button will only appear if Script Debug Mode is checked in theDevelopment menu.
Errors During Compiling

A Script Error dialog is displayed when your script cannot be compiled because of asyntax error. This dialog is typically displayed when you attempt to compile a change to ascript by pressing the Apply button in the Code Editor. Pressing the Script button willselect the line that caused the error. Correct the error then press the Apply button to
compile the script again.

Caution: If a compile error is generated then the entire script to which it applies will not
be compiled, not just the line or handler that contains the error. If other scripts are
attempting to call commands or functions in this script they will not be able to run until
you correct the problem and compile the script again.
Because LiveCode compiles all the scripts within a stack when it loads them, a ScriptError dialog can also be generated when you load a stack from disk for the first time – ifyou saved a stack that contained a script that could not compile.

Important: Do not confuse the Execution Error and Script Error dialogs. The Execution
Error dialog occurs when a script is running and cannot continue due to an error. Theerror dialog will start with the words "executing at [time]". The Script Error dialogappears when you attempt to compile a script that contains a syntax error. The error
dialog will start with the words "compiling at [time]". The Script Error dialog will never
contain a Debug button because the script that generated the error is not running.
Tip: If you turn on the Variable Checking option in the Code Editor, LiveCode will
require that you declare all variables and enclose all literal strings in quotes. It will report
a script compile error if you attempt to use an unquoted literal or do not declare a
variable. This can be useful in catching mistakes before you run a script. Note that if you
turn this option on and attempt to compile an existing script that has not been written in
this way, it will typically generate a large number of errors that need to be corrected
before you can compile it.
10.1.2 Suppressing Errors and Messages
If your stack gets into an unstable state where it is generating a large number of errors,
you may want to temporarily turn off sending messages to the stack or displaying error
messages. This can enable you to edit the stack to make the appropriate changes.

 
To suppress messages, press the Messages button on the toolbar or choose SuppressMessages from the Development menu. Normal system event messages will stop being
sent to the stack (for example clicking a button will no longer trigger a mouseUp handler,
changing card will no longer trigger an openCard handler). You can still send custommessages directly to objects within the stack.

To suppress errors, press the Errors button on the toolbar or choose Suppress Errors fromthe Development menu. This will prevent any errors from triggering an error display
window.

Caution: Be sure to turn messages and errors back on when you have finished editing.
Otherwise your stack will not work, or any error that comes up during stack operationwill cause execution to halt but will not display an error message.
Tip: You can execute a single navigation command in the message box with a
similar effect as Suppress Messages by including the statement lock messages;
before it. for example, to go to the next card lock messages; go nextor to exit
LiveCode (without displaying triggering any close messages or asking to save changes
lock messages; quit
10.1.3 Outputting information as your script executes
If you want to know about the state of a particular variable or condition during execution,
you can use the Variable Watcher, detailed below. However sometimes you may want to
run a script without opening the debugger, outputting information along the way. You
can use the put command to output information to the Message Box, a field or a text
file, the write command to output to the Console, or the answer command to display
a dialog.

Output to the Message Box

The Message Box is a convenient way to output information while a script is running. Itallows you to display the information you want within the IDE without having to create afield or stack to display the information. Using a put command without specifying adestination outputs to the Message Box:

put tVar

In the example above, substitute tVar with the name of the variable in your script that you
want to see the contents of. You can also output information only if a certain condition ismet:

if tVar is true then put tData

 
Whenever you display something in the message box, a special global variable called
message (often abbreviated to msg) is updated. This allows you to check the contentsof the message box easily, as well as add or append information rather than replacing it.

-- puts tInformation and a return after the data
--already in the message boxput tInformation & return after msg

For more information, see the section on the Message Box, above.

Output to Standard Out (stdOut or the Console on Mac OS X)

The stdOut is a useful place to log messages. Unlike the Message Box, it is easy to log asequence of events which you can then scroll back to review later on. It also has theadvantage of being external to LiveCode so using it does not interfere with your
application window layering or focus in any way. The stdOut is only available on Linux,
Unix or Mac OS X systems. On Mac OS X, it can be accessed by opening the Consoleapplication, located in the Utilities folder within Applications.

The syntax to write something to stdOut or the Console is:

write tMessage & return to stdout

Tip: If you are writing a lot of data out to the console, it can be useful to append the time
to each one to make it easier to debug. write tMessage && the long time &
return to stdOut. If you need more granualarity than seconds, use the
milliseconds instead of the long time.
Tip: If you are inserting debugging output statements into your code, consider making
them conditional on a global variable. This allows you to turn on debugging by setting
the variable without making changes to code. Even better it prevents forgotten debugging
code in your application inadvertently filling the console with messages on an end user's
system.
if gDebugging then write tMessage & return to stdOut
Output to a field

You can create a stack that contains fields used for debugging:

put tVar & return after field "debugging info" of \
stack "my debug stack"

 
Tip: You may want to create a set of tools that makes it easy to debug a specific
application you are working on. Create this stack then save it into your plug-ins folder so
it is available from the Development menu in the IDE.
Output to a dialog

To display a dialog with the contents of a statement, use the answer command. Thismethod is suitable if you want to output something quickly, but is usually unsuitable for
larger debugging tasks as it pauses execution to display a dialog each time

if tVar is true then answer tVar

Output to a text file

If you want to log information more permanently, you can use a text file. You may wantto store the file path in a global variable so you can change it easily. See the section on
using file URLs, below for more information.

put tVar & return after URL "file:debug.txt"

10.1.4 Interrupting Execution
If you need to interrupt a script while it is running, press control-period (or commandperiod
on Mac OS). Note that interrupting a script will only work if the globalallowInterrupts property is set to true.

Tip: On Mac OS X systems, if your application has got into an unstable state and you are
unable to interrupt it with command-period you may be able to interrupt it and regain
control by sending it a signal. Open the Terminal utility and then use top -o cpu or ps axto retrieve the process ID for LiveCode. Then run kill -sighup [processID] where
[processID] is the ID of the LiveCode process.
10.2The Debugger

Typically when you want to track down a problem with your script, you will want to usethe debugger. The debugger provides a simple interface that allows you to step through
your script line by line as it executes. You can see the results of each statement as ithappens. If you load the Variable Watcher from within the debugger, it will show you thecontents of all of the variables used in a particular handler. These values will be updated
as you step through. You can even edit these values while your script is running. This can
be useful if you spot a problem in a given area or want to test a section of code with adifferent set of data as it runs.

To activate the debugger, first ensure that Script Debug Mode is turned on in theDevelopment menu. Then open up the script you want to debug and click in the gray bar
to the left of the line where you want to open the debugger. Alternatively you can write

 
the command breakPoint into the script. Using the breakPoint command allows
you to break conditionally – if tVar is true then breakPoint.

Next run your script as normal. When LiveCode reaches a breakpoint it will pauseexecution and load up the debugger.

Important: To see the contents of variables while your script is running, wait for thedebugger to open then choose Variable Watcher from the Debug menu. For more
information on using the Variable Watcher, see below.
Figure 80 – The Debugger

For a table describing each of the buttons in the debugger together with their keyboard
shortcuts, see the section on The Debug Menu in chapter 3.

Press the Step Into button to execute the current line and move to the next line. Step Over
performs the same action, except that if the current line calls a function it will run thatentire function without opening it in the debugger.

Once you have found the cause of the problem, press the Run button to exit the debugger
and run the script at full speed. Alternatively press the Abort button to halt execution on
the current line and edit the script.

 
Tip: To improve the performance when debugging a complex script, set a breakpointfurther down in the script during the debugging process and press the Run button instead
of pressing Step Over. The debugger is temporarily deactivated until the new breakpoint
is reached, which means the script runs at full speed. When using Step Over, the
debugger is still active even though it does not display a routine as it runs, which is
slower.
10.3The Variable Watcher


Context menu
Choose the execution context to display. This will show all theavailable contexts that are currently executing. For example, if you
have a button that has called a function and you are currently
paused within that function, the variables displayed will be for thatfunction. But you can go back and look at the variables in thehandler that called the function by choosing it from this menu.

Conditional
Attach a conditional breakpoint to a variable. In the example above,

breakpoints
if you want a breakpoint to be triggered when tVar contains 2, click
on the breakpoint area to the left of tVar and type tVar = 2 into thedialog. Press the Run button in the debugger. Execution will halt iftVar becomes equal to 2.

List of variables
This lists all the variables in the current execution context. The
contents of each variable is listed in the area on the right. If thecontents is truncated, click on a variable to have the full contentsdisplayed in the edit area at the bottom. The display area is updated
each time you step to the next line while debugging.

Edit area
Display and the contents of the currently selected variable. To
change the content, simply enter a new value.

Edit script
Go to the Code Editor or debugger window for the current

 
execution context.

10.4Custom Error handling

If you are creating an application that is going to be distributed, you may want to includea method for catching and handling errors. LiveCode provides two such methods. Thefirst is the try/catch control structure. This control structure can be inserted around
any routine that you know may encounter problems when in use. For example, you may
wish to include this around a routine that reads in a file from disk to handle the case
where a corrupted file has been selected. The second method is to write a customerrorDialog routine. Unlike a try/catch control structure, an errorDialoghandler is global to your application (or card or stack within an application) and does notprovide a mechanism to allow a script that encounters an error to continue. Use thismethod to display a custom error dialog when an error occurs that you are unable to
predict and report using try/catch.

Using try/catch

Enclose code that may be error prone within a try control structure. The following
example shows a routine that opens and reads from a file enclosed in a try statement. Ifan execution error occurs in any of the statements after the start of the try controlstructure, the catch clause will be triggered with the details of the error. In the examplebelow we declare a variable someError to contain details of the error.

try

open file tFile

read from file tFile until eof

 close file
catch someError

 answer "An error occurred reading a file" && someErrorend try

Tip: The data returned to the error routine is returned in the internal format that
LiveCode uses to display execution errors. To look up the human friendly string
associated with a particular error, look at the first item returned against the list ofexecution errors stored in the LiveCode IDE.
put line (item 1 of someError) of the cErrorsList of \
card 1 of stack "revErrorDisplay"
This will only work in the IDE.
If you want to include statements that will be run regardless of whether there has been an
error or not, include the statements as part of a finally clause.

 
To create readable error messages for cases where you anticipate there may be an error,
use the throw keyword. For example, if we want to display an error message when theresult for opening a file returns something:

open file tFileif the result is not empty then throw the result

In the example above, if the file cannot be opened and the result is set, the value of theresult will be passed to the catch statement in the someError variable.

Writing a custom errorDialog routine

When an execution error occurs, an errorDialog message is sent. The IDE uses thismessage to display the execution error dialog. However you can write and include your
own custom errorDialog routine. This is useful if you are planning to distribute your
application. For example, you could create a stack that transmits the error information
directly to your technical support department or displays a custom message on screen. Abasic errorDialog routine is shown below:

on errorDialog pError

answer "There was an error" && pErrorend errorDialog

This routine will also be activated if you use the throw keyword to throw an error
(outside of a try/catch control structure).

10.5The Message Watcher

The Message Watcher lets you see what messages are sent during a particular operation.
it can be useful if you want to create a log of the sequences of messages generated during
a particular operation. It also logs how long each message takes to run. This makes ituseful when you are looking for bottlenecks in your code. The Message Watcher islocated in the Development menu.


 
Message list area
Figure 81 – The Message Watcher Window
Lists messages as they happen. The format is the name of the
message, the time the message was sent and the number of
milliseconds since the last message. Click to select a message,
double click to open it in the Code Editor.
Object field
Message type
Active
Clear
Suppress
In the example above we can see that the user was inactive for 4.7
seconds before moving the mouse over an object that triggered a
mouseEnter message. 599 milliseconds later they clicked the mouse
triggering a mouseUp message. The mouseUp handler called
calculateResult 0 milliseconds later, then formatData was called
147 milliseconds later. Because there were no user-generated
messages in the sequence, we know that the calculateResult handler
took 147 milliseconds to run.
Shows the object that the message was sent to. Click on a line in theMessage List to update this field.
Shows the type for the selected message – command, function,
getProp or setProp
Check this box to activate the Message Watcher. Deactivate theMessage Watcher when you have captured information about thesequence of events you are interested in and want to stop the
logging of additional messages.
Clears the message list field.
Allows you to set what messages you want displayed and which
ones you want to suppress. Use this option to narrow down themessages that are logged so you can see information about the
sequence you are interested in. See below for more information.


Figure 82 – Suppress Messages Option Screen

 
Action – Handled Don't log any message that causes a handler to run when it is sent.
Action – Not Don't log any message that does not cause a handler to run when itHandled is sent. This is the default option and prevents the log from filling
– Handled Don't log any message that causes a handler to run when it is sent.
Action – Not Don't log any message that does not cause a handler to run when itHandled is sent. This is the default option and prevents the log from filling

up with messages that do not cause any scripts to run.

IDE Messages
Do not log LiveCode IDE messages. The LiveCode IDE generateslots of messages as it is written in LiveCode. This is the defaultoption but you may wish to display these messages if you arecustomizing the LiveCode IDE.

Handler Type
Do not log the selected type of handler. For example, to preventdisplaying all function calls, check the function box.

Message list
A list of messages not to log. By default mouseMove is listed as
otherwise mouseMove messages may flood the display whenever
you move the mouse.

Add Add a message name to prevent it from being logged.
Delete Delete a message name to cause it to be logged in the future.

10.6Tracking Down Problems in Standalone Applications

We recommend that you debug your application as fully as possible in the IDE, so thatyou can use the Debugger and other tools. However occasionally you may need to track
down a problem that only occurs in a standalone application. If this happens, use thetechniques described above for writing information out to the stdOut or a text file. You
can also include an error display dialog using the Bug Reports tab within the Standalone
Settings screen. Be sure to check either the Allow user to save report to file or Allow user
to email report buttons so that you can view the error generated. For more information,
see the chapter on Distributing your Application.
February 21, 2014, at 12:54 PM by Massimiliano Vessi -
Changed lines 1713-1729 from:
9.1 Building a Standalone Application
When you have finished your LiveCode application and what to distribute it you can
build it into a standalone application. These applications do not require users to haveLiveCode. All of LiveCode's feature set is available for use in a standalone application,
with the exception that you cannot set scripts on objects.

The builder itself will let you build standalone applications for any platform it supports,
from any platform it supports (for example you can build a Windows standalone on aMac OS X machine). However, you may wish to check that your application looks and
behaves correctly on each platform you intend to support. Please note it is inherently
harder to debug an application that has been built as a standalone, so you should test your
application as thoroughly as possible before building it.

9.1.1 Standalone Applications Settings
The Standalone Applications Setting dialog allows you to create settings for your
standalone application. This dialog can be found in the File menu. The settings you enter
are applied to the current front most editable stack and are saved with the stack. Thismeans you only need to enter the settings once for each application you create. The samesettings will apply if you do another build in the future.


to:




Deleted lines 1718-2143:
Figure 70 – Standalone Settings – General Tab

Mode Selector
Choose between the different standalone application settings
screens.

Standalone Name
Set the name of your standalone application. This should be the
name you want your finished application to have. Don’t include afile extension (.exe on Windows or .app on Mac OS X) as thestandalone builder can create standalones for multiple platformsand will add the appropriate extension automatically.

Inclusions Choose the components you want to include in a standalone. You
Selector may either choose to search for required inclusions automatically,
or manually select the components you want to include.

Search for Inclusions

This is the default option. When selected, LiveCode will search your application stack
file (main stack and sub stacks) to attempt to determine what components your
application uses. It will then include those items.

Select Inclusions for the Standalone Applications

Select this option if you want to specify the components to include manually. You may
wish to use this option if your application dynamically loads components that cannot besearched at this point automatically, or if you know exactly what components your
application uses and wish to speed up the standalone building process by skipping theautomatic search step.
It is important that you choose to include all the components that your application uses or
it may fail. If you do not include your own custom error reporting or LiveCode’sstandalone error reporting dialog (discussed below) such failure may be silent – i.e. an
operation in your standalone will simply cease working without displaying anything to
the user.

Ask Dialog
This option is required if any of your scripts use the "ask" or "ask
password" commands. The standalone builder will copy the stack
"ask dialog" from the IDE into your standalone as a sub stack. Thestandalone builder makes a copy of your stack before adding
resources to it as part of the build process, so your original stack is
unaltered.

Answer Dialog
This option is required if any of your scripts use the "answer"
command. Note that this only applies to the dialog form of thecommand. The answer file / printer / color / effect / folder / pagesetup / printer and record forms of the command do not requirethis option. The standalone builder will copy the stack "answer
dialog" into your standalone.

Cursors
This option is required if your application uses any of LiveCode's
cursors. It is not required if your application only uses OS cursors.
It copies the stack "cursors" into your standalone.

Print Dialog
This option is required if your application uses LiveCode's built-in

 
Brushes

Script Libraries

Animation
Browser
Database
Font SupportGeometryInternet
Printing

LiveCode Zip

SpeechSSL & EncryptionTable
Video Grabber
XML
XMLRPC

Database Support

Profiles Settings

print or page setup dialogs (e.g. for use on Linux without GTKinstalled). It is not required if you only display the system printer
and page setup dialogs. It copies the stack "print dialog" and
"page setup" into your standalone.
This option is required if your application uses any of LiveCode's
brush cursors. It is not required if your application does not makeuse of the painting commands. It copies the stack "brushes" into
your standalone.
This option allows you to copy script libraries into your
standalone.
The list of available libraries is automatically updated to include
any plug-in libraries or externals you may have installed into theLiveCode distribution. Thus the list you have may differ fromwhat is documented here.

When included in a standalone application, each script library is
implemented as a hidden group and made available when the
group receives its first openBackground message. During the
first part of the application startup process before this message is
sent, any commands that use a given library will not be available.
This may affect attempts to use this a script library in startup,
preOpenStack, openStack, or preOpenCard handers in
the main stack. Once the application has finished starting up, thelibrary is available and the script library can be used in any
handler.
This library is unsupported.
Embedded browser and any revBrowser command.
Database access and any revDatabase command.
revFontLoad and revFontUnload.
Geometry properties or commands.
Internet access, including URL, ftp & POSTrevPrintField, revShowPrintDialog and
revPrintText
All revZip commands (but not required for
compress/decompress)
revSpeak and revSpeechVoicesAny SSL or encryption related commands
Use of the table objectAny video capture commandsAny revXML commands
Any revXMLRPC commands

This option is required if you use SQL databases. Ensure you
choose to include drivers for any database you need to access.


Choose between the Property Profile settings options. You only

 
need to alter settings in this area if you have used Property Profiles(see the section on Property Profiles in Chapter 4, Builder a User
Interface above)
(see the section on Property Profiles in Chapter 4, Builder a User
Interface above)

Remove all
Removes all profiles and builds the standalone using the currently

profiles
active profile on each object. Select this option if you don't need to
change profile in the standalone and want to save disk space by
removing extraneous profile information.

Set all objects to
Set all objects to a specific profile then remove the profile data

profile
from objects.

Include profiles
Include the profile library and allow switching between profiles in

and the profile
the standalone application. You can choose whether to include

library
specific profiles or all profiles.


Figure 71 – Standalone Settings – Stacks Tab

Stack Files
Use this section to add additional stack files to your application.
Any stacks you add to this section will be added to thestackFiles property of the main stack of your standalone. Thismeans that any scripts within your standalone application will beable to locate and reference these stacks by name.

Advanced
Use this section to control exactly how multiple stack files are

Options
managed in your standalone.

Move substacks
If you select this option, each of the sub stacks in the stack files you

into individual
select will be moved into their own individual file, located in the

 
files
Rename stackfiles
generically
Rename stackfiles
generically

Create folder for
stackfiles

Individual stack
options
Set destroyStackto true

Encrypt withpassword

data folder or within the application bundle of your standalone.
Renames each sub stack file using a number on disk (instead ofusing the name of the sub stack). Select this option if you do notwant the names you have selected for stacks to be visible to the end
user in the filing system.
Creates a folder and places the stack files into that folder, instead ofstoring them at the same level as the standalone executable. Allreferences in the stackFiles property will refer to this folder
using a relative path so the stacks can still be located by thestandalone application.
Select a stack file on the left then an individual stack from within
the file to set options on that stack.
Set this option if you want the selected stack file to be removed
from memory when it is closed. This option is useful if you areloading large stacks into memory and want them to be removed
when they are closed.
Secures the scripts within the selected stack file with a password.
This provides a basic level of encryption that prevents someonefrom casually reading the scripts in the stack by opening the file in
a binary file viewer.

Note: A stack file directly attached to a standalone application cannot have changes
saved to it. This stack is bound directly to the executable file that runs. The OS locks anexecutable file while it is running. If you want to save changes in your standalone
application, split your stack up until multiple files. A common technique is to create a
"splash screen" stack that contains a welcome screen and then loads the stacks that makeup the rest of your application. These stacks are referenced as stackFileson this
pane in the standalone settings screen. It is thus possible to automatically update these
component stacks, or to save changes to them. You may also want to consider creating
preference files in the appropriate location on your end user's system (see the
specialFolderPath function and query/setRegistry functions for more
information).
 
Figure 72 – Standalone Settings – Copy Files

Non-stack files in List other files to be included in the standalone. Use this feature to
the application include help documents, read me files and other resources that you

want to include with your standalone each time you build.
Copy ReferencedLoops over all image and player objects in stacks and copies any
Files files referenced in the fileName property of these objects into the

standalone. Then automatically sets the fileName property to
reference these files in the standalone using referenced file paths.
Destination folder Create a subfolder within your standalone to copy the image and
movie files to.

Figure 73 – Standalone Settings – Mac OS Classic

 
Build for Mac OS

Creator signature
Document type
Include resources
from file
Use dynamic
memory
allocation
Minimum /
preferred size

Version number
Long versionstring
Release
Region
Non-release

Builds a standalone for the Mac OS Classic platform. Note that thisbuild option uses the LiveCode 2.6.1 Classic engine. All of thesettings on this pane relate only to the standalone built for Mac OSClassic. They do not affect the other platforms.
Set the creator type for your application
Set the document type for your application
Copy resources from a specified resource file into the resource fork
of your standalone
Use the dynamic memory allocator on Mac OS Classic

Set the minimum and preferred size for your application. Ensurethis is enough to load your application. If you have turned offdynamic memory allocated, ensure this is enough to load all theresources in your application and use the entire feature set
Set the version number, displayed in the Get Info window
Set the version information string, displayed in the Get Info
window
Specify the release type
Specify the region
Specify the non-release version number

 
Important: Because the build for Mac OS Classic option builds using the LiveCode
2.6.1 engine, you must make sure that your stack does not use any newer features that
would cause the scripts not to compile. The standalone builder automatically saves thestack in legacy 2.6.1 format but does not check your scripts. You should check your
stack with a version of the 2.6.1 IDE and use this facility to build for Classic on stacks
that you know are compatible.
Figure 74 – Standalone Settings – Mac OS X Figure 74 – Standalone Settings – Mac OS X
Mac OS X Build a standalone for Mac OS X in universal binary format. This(Universal) standalone will run natively on both Intel and PowerPC machines.
Mac OS X Build a standalone that will run natively on Mac OS X PowerPC

 
(PowerPC Only)

Mac OS X (IntelOnly)
Application Icon

Document Icon

Icons for ask /
answer dialogs

PLIST – enter
information and
have LiveCode
write the PLIST

Choose a file to
import into theapplicationbundle
Short version /
long version
Get info string

Copyright notice
Bundle identifier

machines. This standalone will still run on Intel machines, but willload under Rosetta (emulation) so will run much slower. Choose
this option if you want to keep the file size of your standalone down

(e.g. to upload smaller PowerPC and Intel distributions for your
users to choose from and download).
Build a standalone that will run natively on Mac OS X Intelmachines. This standalone will not run at all under PowerPC.
Choose an application icon to represent the application in theFinder. The icon should be in icns format.
Choose a document icon to represent your application's documents
in the Finder. The icon should be in icns format.
Choose an icon to display whenever you use the ask or answer
commands to display a dialog. On Mac OS X, the convention is thatthese dialogs should display your application icon. The icon should
be stored in your stack as an image, or selected from LiveCode's
built-in icons. If you have used a built-in icon, be sure to select therelevant inclusion on the General tab (if you are selecting inclusionsmanually).
Have LiveCode fill out the PLIST for your application
automatically. The PLIST is a settings file stored in XML formatstored as part of every Mac OS X application. It containsinformation about the application, including its name, version
number, copyright notice and document associations. Having
LiveCode create this file for you is the recommended option. For
more information about PLISTs see
http://developer.apple.com/documentation/
Darwin/Reference/ManPages/man5/plist.5.html

Choose to import a PLIST file instead of having LiveCode create
one. Select this option if you have created your own highly
customized PLIST that you want to use for your application in each
build you create.
The version information to be included with your standalone.


The visible text displayed in your application's Get Info window by
the Finder.
The copyright notice for your application.
A unique identifier for your application used by Mac OS X to
identify your application.


 
Figure 75 – Standalone Settings – Windows

Build for Build a standalone for the Microsoft Windows OS.
Windows
Application icon Choose an application icon to represent the application in

Windows. The icon should be in .ico format.
Document icon Choose a document icon to represent your application's documents

in Windows. The icon should be in .ico format.
Version The version information to be stored as part of your application and
information displayed in the Windows property inspector and dialogs.
Make U3 Build your application for the U3 smart platform. For more
Compatible information on U3 see http://www.u3.com. For more

documentation on building U3 applications using LiveCode, see theResources/Examples/U3 Documentation.pdf file included within
your LiveCode distribution folder.

 
Figure 76 – Standalone Settings – Unix

Build for Linux
Build a standalone for Linux

Build for Solaris
Build a standalone for Solaris

Include
Select built-in LiveCode dialogs to include. These dialogs are
useful if your application may be run on a system that does notinclude these dialogs as part of the OS. You do not need to includethese dialogs if you are running a recent version of GTK.

 
Include Error
Reporting Dialog

htmlText for
dialog

Dialog icon

Allow user to
enter comments
Allow user to save
report to file
Allow user to
email report

Figure 77 – Standalone Settings – Bug Reports

Include an error reporting stack in your standalone. You should
select this option if you are testing your application and wantdetails of any errors in your standalone, or if you have not included
your own error reporting routines in your stacks.
The text to display to the user in the dialog that comes up when an
error is encountered. This text should be in LiveCode-compatibleHTML format. Create and format the text in a LiveCode field then
copy the field's HTMLText property.
The icon to display in the error dialog. This should be stored as an
image in your stack.
Display a box for the user to give you more information. Thisinformation will be included in the report.
Allow the user to save the report to a file. Select this option if you
want users to save an error report and send it to you.
Allow the user to email the report. Select this option if you want theuser to be able to send you or your technical support departmentdetails of the error. This option loads up the system default emailclient and populates the email with the contents of the error reportand the user's comments. The To: field is sent to the email address
specified in the email address field.

 
9.2 Distributing On the Web
To distribute for the web, check the Web option in the Standalone Settings dialog. Thiswill allow you to create a revlet, which can be viewed in in popular browsers using thefree, lightweight revWeb plugin. The latest version of the plugin will always be availableat http://revweb.runrev.com/ and you can direct users there to download it. Note thatbuilding for the web is the only option in revMedia.


Figure 78 – Standalone Settings – Web

UUID
A unique ID for your revlet. This is generated automatically and
shouldn’t be changed.

Security
Allows you to specify the security permissions that your revlet
requires. The revWeb Plug-in will request these permissions fromthe user before your revlet is loaded onto the page. Note that if your
stack requires permissions that have not been granted, thosefeatures will not work. Auto-detect attempts to detect the required
settings from the scripts you use.
Network: Allows access to sockets and URLs outside the domain
the revlet resides on.
Disk: Allows access to the user’s local disk. All file access

 
commands require this permission.
Registry (Read): Allows reading the registry on Windows using
queryRegistry.
Registry (Write): Allows writing to the registry on Windows using
setRegistry.
Privacy: Allows access to the video camera, microphone and screen
capture.
Process / Shell: Allows access to the command line and the ability
to launch and communicate with other processes.


 Printing: Allows access to the printer and printer settings.
Platforms The platforms the revlet supports.
supported
Custom load icon Allows you to specify your own custom logo for use on the loading

screen.

Background
Sets the top and bottom colors to create a gradient color for theloading screen. (Use the same colors for both to create a solid
color.)

February 19, 2014, at 02:19 PM by Massimiliano Vessi -
Changed lines 1706-1715 from:
Chapter 9 Deploying Your Application

With LiveCode, it is easy to deploy your application to anyone. With the revWeb plugin
technology you can deploy to modern web browsers on Windows, Mac OS X and Linux.
revWeb is quick, easy and free for users to install. Simply save your stack as a revlet to
run in a browser. You can also deploy desktop revlets that run using the revWeb runtime
. 

With the standalone building capability in LiveCode you can create a native desktop
application for each operating system you want to support. Users who do not haveLiveCode can run these applications like any other application they download and install.
Standalone applications can have their own identity as true applications, include adesktop icon, document associations and more.
to:
!Creare un eseguibile

Gli script Livecode di solto girano solo se avete installato Livecode sul vostro PC. Livecode vi permetto comunque di creare dei programmi eseguibili per ogni tipo di PC senza che ci sia installato Livecode.
Andate su ''File->StandAlone Application settings'' e decidete per quali sistemi operativi volete creare l'eseguibile ed eventuali opzioni. Una volta fatto cio' andate su ''File->Save as standalone'' e il vostro programma sara' creato all'istante
.
February 18, 2014, at 02:32 PM by Massimiliano Vessi -
Changed line 1 from:
%rfloat%[[http://livecode.com/ | Attach:lccc3.png]]
to:
%rfloat%[[http://livecode.com/ | Attach:lccc2.png]]
February 18, 2014, at 02:32 PM by Massimiliano Vessi -
Changed lines 1-2 from:
%rfloat%[[http://livecode.com/ | Attach:lccc2.png]]
to:
%rfloat%[[http://livecode.com/ | Attach:lccc3.png]]
Changed lines 1696-2074 from:
8.8 Printing a Card
Once you have set your printer, paper and job options (above) you are now ready to useone of the print commands to start printing. At its simplest, the print card command
allows you to print a card. Later we will discuss ways of printing more complex layouts,
fields and text.

print this card -- prints the current cardprint card 12 -- prints card 12

For more details on how to specify which cards to print, see the print command in the
LiveCode Dictionary.

To print a scale between 1 and 100% set the printScale to a number between 0 and 1.
To print at 200% set the printScale to 2.

Important: The printScaleapplies to each card that you print. It is not related tothe printPaperScale which is applied to the entire print job after all other scaling
calculations have been applied. Thus you may set the printPaperScaleto 0.5 to
print at 50%, then print individual cards at different printScale values. With a
printPaperScale of 0.5, a printScale of 2 would result in that card being
printed at 100%.
When printing a card, use the printMargins to specify the margins around the border
of the card on the page.

 
Note: When calculating placement on the printed page, all calculations assume thatthere are 72 dots per inch – regardless of platform or printer device. LiveCode will
automatically adjust the print out for resolution of the actual device. This makes it simple
to calculate your printed layout.
-- a one-inch margin on each sideset the printMargins is set to 72,72,72,72

Important: printMargins only applies when using print card directly. It does not
have any effect on printing cards into a layout (described below).
The printCardBorders property specifies whether or not the bevel border around
the edge of a card should appear in the print out.

8.8.1 Card Layout Options
When using the basic print card form of the print command, there are two layout optionsthat allow you to customize the positioning of cards on the printed page. If you requirefurther flexibility, see the section on printing a layout, below.

Use the printRowsFirst property to specify whether cards should be printed acrossand down or down then across.

Consider a simple example of printing multiple cards – this example is useful for printing
labels. In this example we have a stack that contains 8 cards, each one containing amailing label. If you want to try out this example:

*
Create a stack and size it to be small – the size of a mailing label
*
Create a single field, and in the field Inspector turn off the Shared Text property
*
Group the field and in the group property Inspector turn on Behave as
Background
*
Turn on Select Grouped on the Toolbar and select the field
*
Place the contents of the first mailing label into the Contents tab of the Inspector
*
Create 8 more cards, and in each select the field and place the contents of adifferent label
Thus we have a stack that looks like the figure below.

 
Figure 60 – Print label stack example

Now we will implement the printing commands. If this was a real application you would
probably want to put these in a Print command in the File menu. In this instance you may
execute the following in the multi-line message box (open the Message Box then pressthe second icon to get the multi-line pane).

-- allow the user to choose printer output optionsanswer printerprint 9 cards

Press enter to execute the commands.

The resulting print out will look like the figure below.


Figure 61 – Printing 9 label-sized cards with default settings

 
If we modify the print commands to include an additional line to turn off theprintRowsFirst:

answer printerset the printRowsFirst to falseprint 9 cards

The resulting print out will look like the figure below.


Figure 62 – Printing 9 label-sized cards with printRowsFirst set to false

Use the printGutters property to specify the margin between each card. By defaultthe printGutters are set to 36,36 or one half inch horizontally and vertically.

In the following example, we print the same label stack but reduce the space between
each label to 1/10th of an inch. To make it easy to see the differente we also turn on
printing of card borders using the printCardBorders property.

answer printerset the printGutters to 7,7set the printCardBorders to true

 
print 9 cards

The resulting print out will look like the figure below.
Figure 63 – Printing 9 label-sized cards with borders and a narrow gutter betweeneach
8.9 Printing Fields & Text
To print a field, use the revPrintField command. This command takes a singleparameter, a reference to a field. This command only allows printing a single field. If you
need to include a header and footer or text you have constructed programmatically, seethe revPrintText command below.

revPrintField the long id of field "text document"

Tip: revPrintFieldis implemented as a script library located in the LiveCodeIDE. The script library creates an invisible stack, sets the rectangle of that stack to the
current paper size, sets the formatForPrinting to true, creates a field, then copies
the contents of the field you specify into this invisible stack. It then prints the field one
page at a time, scrolling the text after each page. Advanced users can locate this library
script by going to the Back Scripts tab in the Message Box, turning on the checkbox for
 
Show LiveCode UI Back Scripts, then editing the script of button "revPrintBack". The
revPrintField handler is near the top of the script.
Use the revShowPrintDialog command to control whether the system printer and
page setups dialogs should be shown by revPrintFieldor revPrintText.

-- show the system printer dialog, but not page setuprevShowPrintDialog true, falserevPrintField the long id of field "text document"

Use the revPrintText command to print plain or styled text together with an optional
header and footer.

revPrintText textToPrint [,headerText [,footerText[,fieldTemplate]]]

The textToPrint is anything which evaluates to a string. If you want to printed styled text,
pass HTML instead of plain text. (To convert a field containing styled text to a HTMLuse the htmlText property.)

The headerText and footerText contains the text to use as a header and footer. You may
include an expression that is computed for each page. For more details on using
expressions, see the LiveCode Dictionary entry for revPrintText.

The fieldTemplate parameter allows you to specify a field reference to use. Fonts in theprint out will be inherited from this field.

8.10Printing a Layout

If you need to print a more complex layout than allowed with the basic print card
command or text printing commands (described above), you can use the print cardinto rect syntax to create any sort of layout you choose.

print card from topLeft to rightBottom into pageRect

The topLeft is the top left coordinate of the current card to start printing at.

The rightBottom is the bottom right coordinate of the current card to stop printing at.

The pageRect is the rectangular area on the paper to print into.

Important: printMarginsonly applies when using print card directly. It does nothave any effect on printing cards into a layout. Use the printRectangleto get theprintable area when working with layout printing.
 
For example, lets say that we want to print the text field from the middle of the stack in
figure 73 below. (You can load the stack shown in the picture by going to your LiveCodeinstallation folder then opening Resources-> Examples-> SQLite Sampler.rev.) We wantthe output to scale to take up the entire width of the paper and half the height.


Figure 64 – Stack with text field to print into a layout

print this card from the topleft of field "theText" \
to the bottomRight of field "theText" into \
0,0,item 3 of the printRectangle, \
round(item 4 of the printRectangle / 2)

This results in the print out shown in figure 74 below.

 
Figure 65 – Result of layout printing command

You can construct a complex layout taking components from multiple stacks by printing
a sequence of rectangles onto the same page. For example, you may have a stack thatcontains a standard header and footer, another that contains a logo, and a layout thatcontains text. Use the open printing command to start a print job, then print each
element into the appropriate rectangle on the paper. The use then close printingcommand to send the print job to the printer. The example in figure 75 below shows two
stacks with printable regions that we want to combine onto a single sheet of paper.


 
Figure 66 – Separate header and body stacks to print into a layout

To print these onto a single sheet:

answer printer -- show the system print settings dialog
open printing -- start a print job-- work with the header stack

set the defaultStack to "header"

-- print the header field onto the top left of the paper

print this card from the topLeft of field "header" \
to the bottomRight of field "header" into \
the rect of field "header"

-- save the bottom of the header

put the bottom of field "header" into tHeaderBottom
set the defaultStack to "report editor"

-- print the table field below the header

print this card from the topleft of field "report table" \
to the bottomRight of field "report table" into \
0,tHeaderBottom,the right of field "report table", \
the bottom of field "report table" + tHeaderBottom

-- send the job to the printer

close printing


Figure 67 – Result of layout printing command with multiple stacks

8.10.1 Printing a complex layout
To print a more complicated layout, create a stack and set its rectangle to the currentprintRectangle. Add rectangular areas for each component you will be printing.

 
Then set Geometry properties (see the section on the Geometry Manager, above for moreinformation) on each of these rectangles so they resize correctly when the stack is scaled.
Set up your print routine so that you open this stack invisibly then resize it to theprintRectangle. This will trigger the geometry routines and scale the rectangular
areas correctly. Then run your sequence of print commands to print into each rectangle.

In figure 77 below, we have set the size of the stack to the printRectangle then
added 4 rectangle graphics. We have named each graphic and turned on the Show Name
property for each so you can see the name.


Figure 68 – Stack template for printing a layout

Next, we set Geometry properties for each of the rectangle graphics. The header graphicis set to scale relative to the right and bottom, with a minimum size limit of 100 pixels(see figure 75 below). The body graphic is set to link the top edge to the header graphic,
the right and bottom to the stack (see figure x below). The footer 1 graphic is set to scalethe right edge and position the bottom edge. And footer 2 is set to position both the rightand bottom.

 
Figure 69 – Example geometry properties for print layout stack

To make the printing template stack take on the size of the paper, we can add thefollowing handler to the stack script:

on preOpenStack

 set the width of this stack to (item 3 of the \

 printRectangle - item 1 of the printRectangle)

set the height of this stack to (item 4 of the \

 printRectangle - item 2 of the printRectangle)
end preOpenStack

We now have a working print template stack. All that remains is to write the script thatprints into the rectangles:

-- prepare to load this stack off screen

hide stack "print layout"

-- this will trigger the stack to resize, which run the
geometry routines, giving us the correct values for eachrectangle

go stack "print layout"

-- now we store these rectangle coordinates in variables

put the rect of graphic "header" into tHeaderRect
put the rect of graphic "body" into tBodyRect
put the rect of graphic "footer 1" into tFooter1Rect
put the rect of graphic "footer 2" into tFooter2Rect

 
-- we can close the layout stack as its no longer needed

close stack "print layout"

-- load the system printer dialog to allow the user to
choose number of copies, etc.

answer printer

-- start the print job

open printing

-- set the stack we are working on to a stack containing
the header
-- you could use any stack or region within a card here

set the defaultStack to stack "header graphics"

-- print from the rectangle of our header group into the
rectangle we stored earlier-- we could use a graphic or any rectangular area instead
of a group

print this card from the topLeft of group "header" to the
bottomRight of group "header" into tHeaderRect
set the defaultStack to "body contents"
print this card from the topLeft of group "body" to the
bottomRight of group "body" into tBodyRect
set the defaultStack to "footer1"
print this card from the topLeft of group "footer1" to the
bottomRight of group "footer1" into tFooter1Rect
set the defaultStack to "footer2"
print this card from the topLeft of group "footer2" to the
bottomRight of group "footer2"

-- send the print job to the printer

close printing

-- check to see if the user cancelled or there was an error

if the result is “cancel” then

-- insert any code you need here to handle cancellation

else if the result is not empty then

-- bring up an error dialog

answer “Printer Error”

else

-- insert any code you need here to handle success

end if

For more information on how to print multiple pages of a complex layout, see the section
on Printing Multiple Pages, below. For information on printing scrolling text fields into
an area within a layout, see the section on Working with Scrolling Fields when Layout
Printing, below.

8.11Printing Multiple Pages

8.11.1 Multiple pages using card printing
To print multiple pages when printing cards, simply specify which cards you want to
print as part of the print command.

 
print {range}

Examples:

-- prints the current cardprint this card-- prints all cards in the current stackprint all cards-- prints the next 10 cards, starting with the current cardprint 10 cards-- prints card 3 to 7 of the current stackprint card 3 to 7 print marked cards-- prints all cards where the mark property is trueprint marked cards

8.11.2 Multiple pages when using layout printing
To print multiple pages when printing layouts, use the open printing command to
open a print job. Then print the layout for the first page (see above). Then use the printbreak command to insert a page break into the print job. Then lay out the second pageand so on. Finally, use the close printing command to send the print job to the
printer.

8.11.3 Working with Scrolling Fields when Layout Printing
To print a single scrolling text field, use the revPrintText command (see above for
more information). If you want to incorporate the contents of a scrolling field within alayout, use the pageHeights property to scroll the field each time you print a page,
then print break to move to the next page.

The pageHeights returns a list of values to indicate how far a scrolling field needs to
be scrolled to avoid clipping a line of text on each page of your print out. (You should
use this feature in conjunction with the formatForPrinting property, above.)

-- store a list of pageHeightsput the pageHeights of field "body text" into tHeightsList-- scroll the field to the start
set the scroll of field “body text” to 0-- start the print jobopen printingrepeat for each line l in tHeightsList

-- clip the field to the bottom of the last visible line
set the height of field “body text” to l-- print the field rectangle-- you may want to add an output "into" rectangle
print this card from the topLeft of field "body text" \

 to the bottomRight of field "body text"
-- print a new page
print break


 
end repeat-- send the job to the printerclose printing

Important: Set the Lock Location (lockLoc) property of the field to true before
setting the height in the loop above to avoid the field “drifting” each time you alter theheight.
Tip: Turn off the scroll bar properties (hScrollbarand vScrollbar) of the field
before printing and set the border width to 0 if you want to avoid printing a border or
scroll bar.
Tip: You can incorporate scrolling fields into a template print layout stack (see thesection Printing a Complex Layout above) to make it easier to manage printing a
complex layout. Create a field in your template print stack instead of a graphic, turn offthe scroll bar, set the border width to 0, the lock location to true and then the geometryproperties as per the section above. At the start of each print job, copy the text font and
size by using the textFont and textSize properties, then the contents of the text
field you want to print using the htmlTextproperty.
8.11.4 Working with Print Ranges
Use the printRanges property to get a list of pages that the user has selected in theprinter settings dialog. Use this property when printing to avoid printing pages the user
has not selected. To use this property, open a system printer dialog, then store theprintRanges in a variable. Then set the printRanges to "all", then send only thepages that were selected (stored in the variable) to the printer.

Note: If you ignore the printRangesproperty LiveCode will handle this settingautomatically. Simply send every page to the printer as normal and LiveCode will ignore
the pages the user has not selected in the print dialog. Handle this option manually only ifyou are printing an extremely complex layout and want to save processing time buildingthe layout for every unselected page.
Use the printPageNumber to get the number of the page currently being printed
during your printing loop.

 
8.12Printing a Browser Object

To print the contents of a browser object, use the revBrowserPrint command. For
more information, see the revBrowserPrint command in the LiveCode Dictionary.
to:
!!Stampare solo il testo un campo

Certe volte vi potrebbe servire di stampare solo il contenuto di un campo, basta usare '''revPrintField'''

 revPrintField the long id of field "text document"

C'e' anche '''revPrintText''' che ha piu' opzioni.

February 18, 2014, at 02:17 PM by Massimiliano Vessi -
Changed lines 1671-1708 from:

8.7 Job Related Options


8.7.1 Printer Font Metrics (Windows)
Windows systems sometimes use different versions of the same font for displaying texton screen and printing. This can result in layouts and line breaks differing between thescreen display and the printed output. To prevent this from happening, you can tellLiveCode to use the printer fonts for display on screen. To do this, set a stacksformatForPrinting property to true.

Do:

Don't:


Set the
formatForPrinting stack Allow the user to directly edit text in fields
property to true before loading a stack in whose formatForPrinting is set to
memory. If the stack is already loaded, true. Attempting to do
this may causeset this property to true then save and display anomalies. Set this property to falsereload it. (Save then use Close and and reload the stack first.

 
Remove from Memory in the File menu). in the File menu).

Generally use stacks with
Create a stack off screen (with formatForPrinting set to true for
formatForPrinting set to true) display on screen, as this will show text that
with your print layout template and copy has been optimized for print display (instead
text into it prior to
printing. of screen display), which is harder to read

on screen.
Set the formatForPrinting before
doing any print layout related Use this property on other platforms –
calculations on the stack. Windows is the only platform that uses

different fonts on screen vs. in a print out.
Set the formatForPrinting to true
on any print preview stack being Use the windowBoundingRectdisplayed to the user. property to constrain display of a stack

who's formatForPrinting has been set
to true – this property will be ignored when
the stack is opened or maximized.

Figure 59 – Dos and don'ts of printer font metrics on Windows
to:
!!Stampare

Per stampare basta usare il comando '''print'''.
  Ecco alcuni esempi:

 print this card
 print card 12
 print this stack

Come vedete potete stampare o solo una carta o tutte le carte di una finestra (stack). Quando stampate le carte di una finestra, andate sempre alla prima card che volete che sia stampata, le altre seguiranno l'ordine numerico:

 go to card 1
 print this stack


Prima di stampare impostate
  '''formatForPrinting''' su ''true'', in questo modo tutti i font saranno quelli per la stampa, poi rimetteteli su ''false''.

!!Creare PDF

Per creare i PDF basta lanciare i seguenti comandi, ad esempio:

 open printing to pdf "./esempio.pdf"
 print
this stack
 close
printing
February 18, 2014, at 02:08 PM by Massimiliano Vessi -
Changed lines 1654-1693 from:

8.6 Paper Related Options
This section discusses how you get and set paper related options – the rectangle area ofthe paper, the paper size, the orientation and the scale to use to print onto the paper.
These paper options apply to all types of printing, i.e. card, field and layout printing.

Use the printRectangle to get the printable rectangle area within the paper (returned
in device co-ordinates). This property takes into account any settings applied by the user
in the Page Setup and Printer dialogs including the print orientation (e.g. landscape or
portrait). The rectangle is represented left,top,right,bottom and is always relative to thetop left of the page – thus the top left will always be 0,0. The printRectangle will alwaysbe within the printPaperRectangle– the rectangular area of the sheet of paper.

Note: The printRectangle property is read only and cannot be set directly – to
alter it you must set other options relating to the paper, for example the
printPaperOrientation (discussed below).
Important: Do not confuse the printMarginsand other card layout printingproperties with paper properties such as the printRectangle. The
printMargins only applies to printing cards using LiveCode's automatic cardlayout capabilities (discussed below). Thus the printMargins has no effect on
printRectangle.
Use the printPaperOrientation to get and set the orientation of your print out.
This property may be set to one of the following values:


portrait: rotated 0 degrees.
landscape: rotated 90 degrees clockwise.


 
reverse portrait: rotated 180 degrees clockwise.
reverse landscape: 270 degrees clockwise.

set the printPaperOrientation to "landscape"

Use the printPaperScale property to apply a scale factor to your print out after allother settings have been taking into account.

Note: The printPaperScale is applied after all other layout and scaling options.
For example, if you have used the layout printing features to print a series of cards at50% scale, then set the printPaperScale, this factor will be applied to the entire
layout after the card layout scaling has been calculated.
To print a range between 1 and 100% set the printPaperScale to a number between
0 and 1. To print at 200% set the printPaperScale to 2.

set the printPaperScale to 0.5 -- 50%

to:
!!Impostazioni avanzate

Potete recuperare l'effettiva area di stampa sul foglio dalla proprieta': '''printRectangle'''. Non confondetelo con la proprieta' ''printPaperRectangle'', quest'ultima indica solo le dimensioni del foglio di stampa, ma non l'area effettivamente stampabile. Molte stampanti, infatti, non riescono a stampare su tutto il foglio.

L'orientamento di stampa si imposta con: '''printPaperOrientation'''. Potete solo scegliere tra ''portrait'' (verticale),  ''landscape'' (orizzontale), ''reverse portrait'' (verticale dall'altro lato),  ''reverse landscape'' (orizzontale dall'altro lato). Esempio:

 set the printPaperOrientation to "landscape"

Il fattore di scala si imposta con: '''printPaperScale'''. Potete impostare un valore usando un numero decimale (1, 0.5, 3, 0.21, ecc.)

Il numero di copie si imposta con: ''' printCopies '''. Ricordatevi di impostare '''printCollate''' opportunamente (''true'' o ''false'').

Per scegliere se stampare a colori o in bianco e nero impostare: '''printColors'''  (''true'' o ''false'').

Quando si stampa con un PC, il sistema applica un titolo di riconoscimento al lavoro di stampa (''job''), potete impostare questo titolo con la proprieta': '''printTitle'''


Changed lines 1673-1717 from:
This section discusses how to get and set job related options – the number of copies,
duplex printing, collation, color, title and printable area.

Important: The available job options all depend on what the currently selected printer
supports (use the printerFeaturesproperty, described above, to retrieve a list offeatures supported by the current printer).
Use the printCopies property to get and set the number of copies to print. TheprintCopies should be set to a value of 1 or more.

set the printCopies to 5 -- print 5 copies

Use the printDuplex property to tell the printer to print double sided. This property
may be set to any of the following values:


none: no double-sided printing
short edge: double-sided printing with tumble (flip the non-facing page)
long edge: double-sided printing without tumble.


set the printDuplex to "short edge"

Use the printCollate property to specify whether to interleave multiple copies of aprint job. If a print job has three pages, P1, P2 and P3, with printCollate set to true

 
and printCopies set to 2 the output order will be P1, P2, P3, P1, P2, P3. With
printCollate set to false the output will be P1, P1, P2, P2, P3, P3.

set the printCollate to true

Use the printColors property to specify whether to print in color or not. If "color" isnot among the lines of the printerFeatures then this property will have no effectand all print jobs will be printed in monochrome. This property may be set to either true
or false.

For example, to check if color printing is supported on the current printer and use it if itis:

if "color" is among the lines of the printerFeatures thenset the printColors to true

Use the printTitle property to specify the name of the next print job in the systemprinter queue. Setting this property to match the name of the user's document will ensurethat the user is able to recognize it in the system printer queue utility. If theprintTitle is empty at the start of a printing loop, the title of the defaultStack
will be used.

set the printTitle to "My Report 1"

Use the printRectangle property to determine the printable region of the physicalpage as returned by the printer. This rectangle will always be contained within theprintPaperRectangle. Thus you should use the printRectangle and not the
printPaperRectangle when calculating a print layout. The
printPaperRectangle is useful if you are generating a print preview and want to
show the entire area of the paper including any margin areas that cannot be printed on.
This property is read only and cannot be set directly.
to:


8.7.1 Printer Font Metrics (Windows)
Windows systems sometimes use different versions of the same font for displaying texton screen and printing. This can result in layouts and line breaks differing between thescreen display and the printed output. To prevent this from happening, you can tellLiveCode to use the printer fonts for display on screen. To do this, set a stacksformatForPrinting property to true.

Do:

Don't:

Set the formatForPrinting stack Allow the user to directly edit text in fields
property to true before loading a stack in whose formatForPrinting is set to
memory. If the stack is already loaded, true. Attempting to do this may causeset this property to true then save and display anomalies. Set this property to falsereload it. (Save then use Close and and reload the stack first.

February 18, 2014, at 01:53 PM by Massimiliano Vessi -
Changed lines 1593-1594 from:
Stampare e' semplicissimo, di solito si crea una o piu' carte (card) e si mandano in stampa. La semplicita' di Livecode vi permettera' di creare anche dei report complicatissimi. Stampare significa che potete anche creare dei PDF. L'unica differenza tra la stampa normale e creare un PDF e' nel dispositivo di stampa che sara' il programma per i PDF invece di una stampante.
to:
Stampare e' semplicissimo, di solito si crea una o piu' carte (card) e si mandano in stampa. La semplicita' di Livecode vi permettera' di creare anche dei report complicatissimi. Stampare significa che potete anche creare dei PDF. L'unica differenza tra la stampa normale e creare un PDF e' nel dispositivo di stampa che sara' il programma per i PDF incluso in Livecode invece di una stampante.
Changed lines 1650-1678 from:

8.5.4 Saving Printer Settings
To save or set a complete set of options relating to the current printer which includesevery setting in the OS Page Setup and Print dialogs, use the printerSettingsglobal property.

The printerSettings property is a binary string that completely describes thecurrent settings. The property contains the name of the printer and the settings currently
in use.

Caution: You should not attempt to modify the printerSettings but rather get and set itin its entirety. To access individual printer properties, use the global printing properties
described below.
When you set the printerSettings property to a saved value, LiveCode will choosethe printer named in the property and set all of its settings to those contained within theproperty. If the printer cannot be found LiveCode will return the error "unknown printer"
in the result. If the printer is found but the settings are not valid then LiveCode willchoose the printer and reset it to default values.

Note: You must save a separate copy of the printerSettings property for each printer orOS you intend to use. The printerSettings property cannot be transferred between
platforms. For example, a printerSettings property generated on a Windows computer
cannot be used on Mac OS X – even for the same printer. If you want to alter settings
across different platforms and printer types use the global printing properties described
below. Use the printerSettings for convenience when you know you will be using the
 
same printer and want to save all the settings, or where you are setting esoteric propertiesnot listed in the global printing properties described below.
To save the current printer settings into a custom property stored on the current stack:

set the cSavedPrinterSettings of this stack to \

the printerSettingssave this stack

Then to restore these settings:

set the printerSettings to the cSavedPrinterSettings \
of this stack
to:
!!Salvare tutte le impostazioni

Tutte le impostazione di stampa sono memorizzate nella proprieta' globale '''printerSettings'''. Questa variabile contiene tutti i dati possibili sulla stampa, ma e' scritto in codice macchina, quindi non pensate che si possa modificare facilmente. Di contro e' comoda per salvare tutte le impostazioni e recuperarle in un secondo momento. Se cambiate pc o sistema operativo, questa proprieta' cambia.

February 14, 2014, at 11:47 AM by Massimiliano Vessi -
Changed lines 1638-1649 from:
Attach:LCanswerPrinter.jpg


To bring up the standard OS printer dialog, use the answer printer command.

answer printer

If the user does not press the cancel button then any changes to the printer settings will bereflected in the global printing properties, discussed below
. 

To bring up the standard OS page setup dialog, use the answer page setupcommand.

answer page setup
to:
Attach:LCAnswerPrinter.jpg

Piu' semplice di cosi' non e' possibile.

Nel medesimo modo per far impostare all'utente di impostare le opzioni di pagina:

 answer page setup

e apparira':

Attach:LCAnswerPageSetup
.jpg
February 14, 2014, at 11:43 AM by Massimiliano Vessi -
Changed lines 1632-1652 from:


8.5.3 Working with Printer Dialogs
In most applications that need to print
, you will want to provide a way to bring up thestandard OS Print and Page Setup dialogs. Typically you would make these dialogsavailable from Print and Page Setup items in the File menu of your application. When theuser makes changes in these dialogs the changes are made accessible to you in globalproperties. We discuss how to save and utilize these properties below.

Note: It is not necessary to bring up the standard OS dialogs to alter printer settings.
You may set the appropriate printer setting directly by script instead.
Note: On Linux & Unix systems you will need a recent version of GTK installed in
order to display the OS printer dialog. If you don't have this installed, LiveCode will
display its own printer dialog which has been built as a stack and script library. Thisdialog mimics the standard system printer dialog and sets the LiveCode printing globalproperties directly.
Tip: You may force LiveCode to use its own internal print settings dialog by setting the
systemPrintSelector global property to false. Advanced users may customize
the printer dialog that LiveCode uses by running toplevel "print dialog"or
toplevel "page setup" in the Message Box. Remember to save a copy of the
stack as it will be overwritten each time you upgrade your copy of LiveCode.
Important: The LiveCode print and page setup dialogs must be included in a standaloneapplication if you use them. Ensure that the check box Print Dialog is turned on in the
 
Standalone Application Settings dialog for your application. You do not need to include
these dialogs if you only use the OS native print dialogs. For more information on
including resources in your standalone application, see the chapter on Building
Standalone Applications.
to:
Se volete far scegliere all'utente, Livecode ha gia' tutto pronto, basta usare:

 answer printer

e apparira':

Attach:LCanswerPrinter
.jpg

February 14, 2014, at 11:24 AM by Massimiliano Vessi -
Changed lines 1618-1651 from:

8.5.1 Choosing a Printer
Use the availablePrinters to list the printers available on the user
's system.
Printers can include fax modems and networked devices. If the availablePrinters
is empty, no printer is assigned. For example, to place a list of the available printers into alist field:

put the availablePrinters into field "list of printers"

Set the printerName to the printer you want to use to print. You can use any printer
listed in the availablePrinters. This property is useful when producing an inhouse
utility that needs to print to a specific printer on the corporate network
, or for
automatically restoring the user
's previous printer choice stored in a preferences file.

set the printerName to the cSavedPrinter of stack \
"My Preferences"

The printerFeatures provides a list of the features supported by the currently
selected printer
. Features will vary widely from device to device, but typical features may
include things such as "collate", "color" and "duplex". Use this property to enable and
disable output options in any custom printer settings dialog.

8.5.2 Choosing Output Mode (e.g. Print to File)
The printerOutput global property allows you to choose the output mode for
subsequent printing commands. This property is set by the system to the default printer

 
on startup and will be changed if you open a system print dialog in which the user
chooses a different printer. If this property is set to device it will output to the physicalprinter. Alternatively, you can set it to a file path to print to a file. On Mac OS X this willcreate a PDF file, on Windows an XPS file and on UNIX a postscript file. On Mac OS Xyou can set this to preview to create a preview.

For example, to save the current card to a file:

ask file "Save as:
set the printerOutput to ("file:" & it )
print this card
to:
Per impostare una stampante basta impostare la proprieta' '''printerName''':

 set the printerName to "Lexmark T640 XL"

Poi potete scoprire che opzioni ha la vostra stampante con la proprieta' '''printerFeatures''':
 put the printerFeatures

nel mio caso e' uscito:
 collate,copies

Cosi' sapete cosa potete attivare della stampante. Nel mio caso e' possibile dire quante copie fare di una stampa (in modo da non dover mandare in stampa tante volte lo stesso documento) e nel caso di copie e' possibile scegliere se stampa prima tutte le prime pagine, poi tutte le seconde, poi tutte le terze
, oppure stampa dalla prima all'ultima e ricomincia per ogni copia (opzione ''collate'').

Altre opzioni potrebbero essere "color" (a colori), "duplex" (fronte retro), ogni stampante ha le sue
.

February 14, 2014, at 11:16 AM by Massimiliano Vessi -
Changed lines 1592-1615 from:
!Stampare
Stampare e' semplicissimo, di solito si crea una o piu' carte (card) e si mandano in stampa. La semplicita' di Livecode vi permettera' di creare anche dei report complicatissimi.


 
 
Printing and Reports

Printing is a vital aspect of many applications. LiveCode provides a comprehensive set ofprinting capabilities. Whether you want a simple print out of your stack, want to printlabels or produce complex reports, LiveCode has the features you need.

 
8.4 Introduction to Printing
LiveCode supports a number of methods of printing. You can use the print card
command and have LiveCode manage the layout of cards on the paper. Alternatively you
can use the print into rectangle commands which allow you to take full control over thelayout of your print out. The former method is most suited to implementing simple printfunctionality, while the latter is better suited for more complex layout printing or printing
reports. Finally, you can use the built-in field printing script library to print the contentsof any text field using a simple command.

LiveCode also includes a full set of features to access and set printer device options,
including options such as margins, page range and number of copies. On Mac OS Xsystems you can also print directly to a
PDF file – even without showing the user a printdialog if choose to. On Windows systems this option will create an XPS file and on Unix
systems a Postscript file. This feature is invaluable if you want to produce a high
resolution file PDF, XPS or Postscript file respectively, from your stack.

8.5 Controlling Printer Device Settings
LiveCode gives you full programmatic control over your printer device and any availablesettings.
to:
!Stampare e PDF
Stampare e' semplicissimo, di solito si crea una o
piu' carte (card) e si mandano in stampa. La semplicita' di Livecode vi permettera' di creare anche dei report complicatissimi. Stampare significa che potete anche creare dei PDF. L'unica differenza tra la stampa normale e creare un PDF e' nel dispositivo di stampa che sara' il programma per i PDF invece di una stampante.

Livecode vi permette di impostare parecchi aspetti della stampante o anche di stampare solo quello dentro ad un determinato rettangolo o solo il contenuto di un campo di testo ''(field)''.

!!Impostare la stampante

Innanzitutto potete scegliere la stampante da utilizzare. Per avere una lista delle stampanti basta usare la proprieta'  '''availablePrinters''':

 put the availablePrinters into field "lista stampanti"

e dovreste ottenere una lista tipo:

 \\RMCSERVER01\PRT_A4V
 PDFill PDF Writer
 Microsoft XPS Document Writer
 Microsoft Office Live Meeting Document Writer
 Microsoft Office Live Meeting 2007 Document Writer
 Microsoft Office Document Image Writer
 Lexmark T640 XL
 ImagePrinter
 Automatico Lexmark T640 su PC22
 Automatico HP LaserJet 2200 Series PCL 6 su RMCSERVER01
 Automatico HP Color LaserJet 3550 su RMCSERVER01
 Adobe
PDF
February 07, 2014, at 03:03 PM by Massimiliano Vessi -
Changed lines 1592-1593 from:
to:
!Stampare
Stampare e' semplicissimo, di solito si crea una o piu' carte (card) e si mandano in stampa. La semplicita' di Livecode vi permettera' di creare anche dei report complicatissimi.
February 07, 2014, at 02:12 PM by Massimiliano Vessi -
Changed lines 1535-1536 from:
E' possibile dare '''qualsiasi''' forma alle finestre, per esempio un ovale:
to:
E' possibile dare '''qualsiasi''' forma alle finestre, anche con buchi, per esempio un ovale:
Changed line 1544 from:
to:
! Database
Changed lines 1546-1566 from:
Chapter 8 Working With Databases

With the LiveCode Database library, your application can communicate with externalSQL databases. (Database access is not available in LiveCode Media.) You can get datafrom single-user and multi-user databases, update data in them, get information about thedatabase structure, and display data from the database in your stack. And with theDatabase Query Builder, you can automate the process of querying a database and
populating fields with the data, with no scripting required. For a discussion of when it isappropriate to use an external database with LiveCode, see the topic When to Use aDatabase in Chapter 2.

This chapter discusses how to install necessary software to communicate with databases,
how to set up automatic database queries using the Database Query Builder, and how to
use the Database library to communicate between LiveCode and a database.

This topic does not include discussion of how to set up and create a SQL database, which
is beyond the scope of the LiveCode documentation.

To fully understand this topic, you should know how to write short scripts and should
understand the basic concepts of SQL databases (rows and columns, database cursors,
and SQL queries).

A few terms used in this topic, such as "field" and "cursor", are part of the standard
terminology for working with databases, but have a different meaning in the context ofLiveCode development. When going back and forth between database work and moregeneral application development, be sure you understand which meaning is applicable in
the context you're currently working in. When referring to database-specific terms, thedocumentation usually uses phrases like "database field" or "database cursor" to remind
you of the context. See the Glossary within the product documentation for definitions ofany term you are unsure of.

to:
Livecode puo' lavorare con qualunque database. Livecode ha integrato SQLite, ma potete interfacciarci con qualunque database cha abbia una interfaccia ODBC (quasi tutti ce l'hanno), ecco i piu' popolari:

* SQLite
* MySQL
* Oracle
* PostgreSQL
* Valentina

I database sono, di solito, dei file esterni al nostro programma che possono essere sullo stesso pc su cui gira il nostro programma o su un server remoto. I database contengono tantissime informazioni catalogate. Grazie ai database noi possiamo ricercare informazioni, inserire o cancellare dei dati, tutto secondo particolari criteri che impostiamo noi.

Il linguaggio utilizzato da quasi tutti i database è il SQL. Generalmente i comandi validi per un database, valgono anche per tutti gli altri.

Riassumendo in poche parole un database, si può affermare che si tratta di una raccolta di tabelle, dentro ogni tabella i dati sono organizzati per righe e per colonne.

I database hanno dei vantaggi:
* veloci a trovare i dati che si servono  tra migliaia di dati
* occupano poco spazio
* sono ottimizzati per fare il loro lavoro
* sono velocissimi
* si riescono ad incrociare i dati di piu' tabelle facilmente

Potreste fare le stesse cose di un database con una matrice, ma trattando molti dati, vi consiglio di imparare ad utilizzare i database.

!!Connessione
Per utilizzare un database bisogna prima connettersi ad un database, utilizzando la funzione revOpenDatabase() e memorizzare l'identificato della connessione. Per esempio con SQLite si scrivera':

 put revOpenDatabase("sqlite", "./mioDB.sqlite", , , , ) into connID

in questo esempio la variabile  ''connID'' contiene l'identificativo della connessione (e' un semplice numero). Potete stabilire piu' connessioni contemporaneamente.

!!Interrogare

Per recuperare delle informazioni dal database, in gergo si dice ''interrogare'', basta usare il comando la funzione '''revDataFromQuery''', specificando come separare righe e colonne:

 put "SELECT * from utenti ; " into tSQL
 put revDataFromQuery(tab,return,connID,tSQL) into tRecords

in questo caso abbiamo che ''tRecords'' contiene tutti i dati dove ogni colonna e' separata dall'altro dal carattere TAB e ogni riga da un accapo. Questa forma potete cambiarla, ma e' molto comoda perchè permette di visualizzare i dati un un campo di testo come una vera tabella  (''field, label'').

!!Eseguire
Per eseguire dei comandi che modificano in database, basta usare il comando  '''revExecuteSQL''', ad esempio:

 put "INSERT into users (name,surname) VALUES ('Jack','Sparrow')" into tSQL
 revExecuteSQL connID,tSQL




Deleted lines 1595-1794:
8.1 Introduction to Database Access
A database is an external resource that holds information, structured in a special form for
quick access and retrieval. Databases can be:

*
any size from small to extremely large
*
located on the same system as the application or on a remote server
*
accessible by one user at a time or by many users at once
8.1.1 SQL Databases
A SQL database is a database that you access and control using SQL, a standard
database-access language which is widely supported. You use SQL queries (statements in
the SQL language) to specify the part of the database you want to work with, to get data,
or to make changes to the database.

LiveCode's database access is fully-featured. You can send any SQL statement to adatabase. You can open multiple databases (or multiple connections to the samedatabase), maintain multiple record sets (database cursors) per connection, and send and
receive binary data as well as text. You can do all this using the Database Query Builder,
or in scripts that use the commands and functions in the Database library.

To see a list of LiveCode terms in the Database library, open the Dictionary, and type
"database" into the search filter field. You can also find a interactive workshop and
tutorial materials on our web site at:

http://www.runrev.com/developers/lessons-and-tutorials/explore-livecode/databases/

8.1.2 Why use an External Database?
See the section on When to use a Database in Chapter 2.

8.1.3 The Basics of Database Structure
A database is built of records, which in turn are built out of database fields. A field is thesmallest part of a database that can be separately addressed. Each database field containsa particular kind of information. This might be a name, a file path, a picture, or any other
kind of information. Each record contains one value for each of its fields. A set of records
is called a database table, and one or more tables comprise a database.

Here's an example: suppose you have a database of customers for your business. Thefields of this database might include the customer name, a unique customer ID number,
and shipping address. Each record consists of the information for a single customer, so
each record has a different customer name, shipping address, and so on.

 
Note: You may have noticed that the database structure being described resembles amultiple-card stack that has the same fields on each card. A database field is like a field
in a stack, and a record is like a card. A stack set up this way can act as a database, in
fact, but lacks some of the features of an external database, such as the ability to performSQL queries and the ability to perform robustly when accessed by more than one user.
You can also think of the set of customer records as a grid (like a spreadsheet). Each rowis a record, and each column is a field, so each cell in the grid contains a different pieceof information about a particular customer. Here's an example:

ID

Customer Name

Address

Country
123 Jane Jones 234 E. Street U.K.
836 Acme Corporation PO Box 23788 USA
823 CanCo, Inc. 1 CanCo Blvd. Japan

Figure 58 – Example Database Grid

There are three rows in this grid (each is the record for a particular customer) and four
columns (each is one of the fields).

A row of the database means one single customer record, which has one value for each
field. A column of the database means the set of all values for one of the fields, one for
each record (for example, the set of all customer addresses).

More generally, each row describes one of the things in the database, and each column
describes a particular state for each thing in the database.

The set of all customer records makes a table. Your database might include only thistable, or it might include other related tables, such as a list of all sales. You can also
connect related data from different tables of the same database. For example, if each
record in the Sales table includes the ID number of the customer who bought the product,
you can link all the sales records for a customer to that customer's record in theCustomers table.

8.1.4 SQL and Record Sets – Database Cursors
SQL works primarily with sets of records, rather than individual rows. When you send aSQL query to a database, the query typically selects certain records which you can
perform further operations on. The set of records resulting from a SQL query is called adatabase cursor, or record set. SQL queries let you describe the characteristics of therecords you require, instead of processing each record one by one to find out whether itmatches your criteria.

For example, consider the customer table we talked about in the previous section. To
work with only US customers, you can write a SQL query that selects only records wherethe country field is "USA". This subset of records then becomes a record set. You can

 
find out more about the fields and records contained in this record set, and move fromrecord to record within this subset of the database. You can create more than one record
set to work with more than one set of records at a time.

Note: Different database implementations have different limitations on movementwithin a record set. For example, some databases won't let you move backward within a
record set: instead, you must start at the first record and move forward in order to
examine the data.
8.1.5 Choosing a Database
LiveCode directly supports the following database implementations:
Oracle
MySQLSQLitePostgreSQLValentina

LiveCode also supports connecting to a database via ODBC. You can use ODBC to useAccess, FileMaker, MS SQL Server and many other database implementations. Seebelow for more information about ODBC.

LiveCode's database commands and functions use the same syntax regardless of whattype of database you are connecting to. You don't need to learn a separate databaselanguage for each type. Instead, when you first open a database with therevOpenDatabase function, you specify the type as one of the parameters so LiveCodeknows what type of database it's dealing with. The Database library handles the details ofeach type behind the scenes for you.

When you use the Database Query Builder, you simply select the database type you want
to use. Like the Database library, the Database Query Builder handles the details for you.
You can easily switch between database types.

8.2 Reasons to Choose a Database Type
Which type of database to choose depends on a number of factors. If you need to work
with an existing database, or already have a database manager installed, the decision ismade for you. Likewise, if you're already an expert at a particular databaseimplementation, you'll probably prefer to go on using that one.

Other factors in your choice may include price, performance, licensing model(commercial or open source), and platform support. If your users are on a particular set ofplatforms, you'll need to choose a database that is supported on all those platforms.
Runtime do not endorse any particular database type, the information provided on thedifferent types is for informational purposes only.

 
8.2.1 Overview of ODBC
Open Database Connectivity (ODBC) is a system that allows developers to access any
type of compatible database in a standard way.

To communicate with a database, you usually have to add code that uses the database's
own proprietary protocols. Without ODBC, in order to create a program that can
communicate with--for example--FileMaker, Access, and Oracle databases, LiveCodewould have to include code for three different database protocols. With ODBC, LiveCodecan communicate with any of these database types using the same code.

ODBC Managers

To work with databases through ODBC, you need two pieces of software: an ODBC
manager, plus a database driver for the specific database type you're using.

Windows 2000 and Windows XP, and OS X version 10.2 and later, include ODBC
software with the operating system. For earlier versions, and for Mac OS and Unix
systems, you can download an ODBC manager and a set of drivers. (See the section
below titled "Software for Database Access" for more information.)

8.2.2 Performance for Direct Access Versus ODBC Access
Typically, accessing a database via ODBC takes more configuration and is slower than
accessing the database directly. For this reason, LiveCode provides the ability to accessMySQL, PostgreSQL and Oracle databases directly without going through the ODBC
protocol. This ability will be valuable for anyone doing complex or extensiveprofessional database work.

The syntax of the functions in the Database library is identical for all database types, so
you do not need to rewrite your scripts to take advantage of the increased efficiency ofdirect access.

8.3 Software for Database Access
To provide connectivity to databases, LiveCode works with database drivers--softwarethat translates application requests into the protocol required by a specific database.

8.3.1 Finding Database Drivers
Database drivers for certain database types are included in the LiveCode distribution.
(The list of included database types depends on the platform.) The sections below listwhich database drivers are included with which platforms.

If you have installed LiveCode, you have all the software needed to use the included
database types. For other database types, you will need to obtain the appropriate databasedrivers before you can work with those databases.

 
Important: This section includes links to third-party web sites and contains information
about third-party software. This information is provided for your convenience, but
RunRev is not responsible for the software packages and sites referenced. Runtime
regrets that it cannot provide any support for installation and configuration of any
databasae.
8.3.2 MySQL
MySQL database drivers are included as part of the LiveCode installation on Linux, MacOS X, and Windows systems.

8.3.3 Oracle
LiveCode includes drivers for Oracle on Windows and (currently) PPC Mac OS X.

To obtain an Oracle database driver for your platform, visit the Oracle web site athttp://www.oracle.com.

8.3.4 PostgreSQL
A PostgreSQL database driver is included as part of the LiveCode installation on Linux,
Mac OS X and Windows systems.

8.3.5 SQLite
Drivers for accessing this database are included with LiveCode. No additional installation
is necessary.

8.3.6 ODBC managers and database drivers
To use a database via ODBC, you must install the necessary ODBC software for your
platform. (Some operating systems include an ODBC installation.) ODBC softwareincludes one or more database drivers, plus an ODBC manager utility.

ODBC on Windows systems

Windows 2000 and Windows XP include the MDAC (Microsoft Data AccessComponents) package as part of the standard system installation. To configure ODBC on
Windows systems, use the ODBC Data Sources control panel.

For earlier versions of Windows, you can download MDAC from the Microsoft web siteat http://www.microsoft.com/data/download.htm.

ODBC on Mac OS X systems

OS X version 10.2 and later includes iODBC software as part of the standard systeminstallation. To configure ODBC on OS X systems, use the ODBC Administrator
application in the Utilities folder.

ODBC on Unix systems

 
LiveCode supports iODBC and UnixODBC on Unix systems. You can download theiODBC software from the iODBC web site at http://www.iodbc.org/. You can download
the unixODBC software from the unixODBC web site at http://www.unixodbc.org.

Creating a DSN for ODBC access

Once you have installed the necessary software, you use the ODBC manager to create aDSN, which is a specification that identifies a particular database.

You use the DSN to connect to the database via ODBC. The following example opens aconnection to a database whose DSN is named "myDB":

get revOpenDatabase("ODBC","myDB",,"jones","pass")

To connect to a database using the Database Query Builder, you enter the DSN's name in
the Database Query Builder window.

Note: One of the advantages of setting up a DSN is that if you wish to change thelocation of the database, you only have to edit the DSN settings, not your application
code. You can think of a DSN as a kind of shortcut or alias to your database.
January 28, 2014, at 04:30 PM by Massimiliano Vessi -
Deleted lines 1543-2032:
7.13Programming Menus & Menu Bars

Menus in LiveCode are not a separate object type. Instead, you create a menu from either
a button or a stack, then use special commands to display the menu or to include it in amenu bar.

This topic discusses menu bars, menus that are not in the menu bar (such as contextualmenus, popup menus, and option menus), how to make menus with special features such
as checkmarks and submenus, and how to use a stack window as a menu for total control
over menu appearance.

To easily create menu bars that work cross-platform, choose Tools -> Menu Builder.
See the section on the Menu Builder in the chapter on Building a User interface for more
details. The details about menu bars in this topic are needed only if you want edit menu
bars by script, for example if you want to include specific features not supported by theMenu Builder.

7.13.1 Menu Types
LiveCode supports several menu types: pulldown menus, option menus (usually called
popup menus on Mac OS and OS X), popup menus (usually called contextual menus on
Mac OS and OS X), and combo boxes.

Each of these menu types is implemented by creating a button. If the button's styleproperty is set to "menu", clicking it causes a menu to appear. The button's menuMode
property determines what kind of menu is displayed.

 
Even menu bars are created by making a pulldown-menu button for each menu, then
grouping the buttons to create a single menu bar. The menu bar can be moved to the top
of the stack window (on Unix and Windows systems). To display the menu bar in thestandard location at the top of the screen on Mac OS and OS X systems, you set thestack's menubar property to the group's name. The name of each button is displayed in
the menu bar as a menu, and pulling down a menu displays the contents of the button as alist of menu items.

7.13.2 Button Menus
You can create a button menu by dragging out one of the menu controls from the toolspalette. However, if you want to create one by script, the easiest is to create a button and
set the style of the button to "menu". Next, you can set the menuMode of the button to
the appropriate menu type. You can either set the menuMode in a handler, or use theType menu in the button's property inspector to set the menu type.

To create the individual menu items that will appear in the menu, set the button's text
property to the menu's contents, one menu item per line. You can either set this property
in a handler, or fill in the box labeled "Menu items" on the Basic Properties pane of theproperty inspector.

When you click the button, the specified menu type appears, with the text you entered
displayed as the individual menu items in the menu.

Tip: To dynamically change the menu's contents at the time it's displayed, put a
mouseDown handler in the button's script that puts the desired menu items into thebutton. When the menu appears, it displays the new menu items.
For menus that retain a state (such as option menus and combo boxes), the button'slabel property holds the text of the currently chosen menu item.

Handling the menuPick message

When the user chooses an item from the menu, LiveCode sends the menuPick messageto the button. The message parameter is the name of the menu item chosen. If you wantto perform an action when the user chooses a menu item, place a menuPick handler like
this one into the button's script:

on menuPick theMenuItem
switch theMenuItem
case "Name of First Item"
-- do stuff here for first item
break
case "Name of Second Item"
-- do stuff here for second item
break
case "Name of Third Item"

 
-- do stuff here for third item
break
end switch
end menuPick

Changing the currently-chosen menu item

For menus that retain a state (such as option menus and combo boxes), you can changethe currently-chosen menu item by changing the button's label property to the text of
the newly chosen item

If you change the currently-chosen menu item in option menus, also set the button'smenuHistory property to the line number of the newly chosen item. This ensures thatthe new choice will be the one under the mouse pointer the next time the user clicks the
menu.

7.13.3 Creating Cascading Menus
To create a cascading menu (also called a submenu, pull-right menu, or hierarchicalmenu), add a tab character to the start of menu items that you want to place in thesubmenu.

For example, the following text, when placed in a menu button, creates two menu items,
then a submenu containing two more items, and finally a last menu item:

 First Item

 Second Item

 Third Item Is A Submenu

First Item In Submenu

Second Item In Submenu

 Last Menu Item Not In Submenu

The depth of a submenu item is determined by the number of tab characters before themenu item's name. The submenu item becomes part of the closest line above the submenu
item that has one fewer leading tab character.

This means that the first line of a menu cannot start with a tab character, and any line in
the button's text can have at most one more tab character than the preceding line.

Important: You cannot create a cascading combo box at all, and cascading optionmenus do not work properly on all platforms. In general, you should create cascading
menus only as a part of a pulldown menu.
Cascading menus and the menuPick message

When the user chooses a menu item in a cascading menu, the parameter of themenuPick message contains the menu item name and the name of the submenu it's part

 
of, separated by a vertical bar (|). For example, if the user chooses the "Second Item In
Submenu" from the menu described above, the parameter sent with the menuPick
message is:

 Third Item Is A Submenu|Second Item In Submenu

7.13.4 Ticks, Dashes & Checks in Menus
There are several special characters that you can put at the start of a line in the button'scontents to change the behavior of the menu item:

-A dash on a line by itself creates a divider line

* !c checks the menu item

* !n unchecks the menu item

* !r places a diamond at the start of the menu item

* !u removes the diamond

If you include any of the above special characters in a submenu item, the specialcharacter must be placed at the start of the line – before the tab characters that make it asubmenu item.

Note: You cannot create divider lines in combo boxes or in option menus on Windows
systems.
There are three other special characters that can appear anywhere in a line:

Putting the & character anywhere in a line underlines the next character and makes it thekeyboard mnemonic for that menu item on Windows systems. The & character does not
appear in the menu, and is not sent with the parameter to the menuPick message when
you choose the item from a menu.

Putting the / character anywhere in a line makes the next character the keyboard
equivalent for the menu item. Neither the / nor the character following it appear in themenu, nor do they appear in the parameter to the menuPick message.

To put an & or / character in the text of a menu, double the characters: &&or //.

Putting the ( character anywhere in a line disables the menu item. To put a ( character
in a menu item without disabling it, precede it with a backslash: \(.

Note: You cannot disable lines in combo boxes or in option menus on Windowssystems.
 
All of the above special characters are filtered out of the parameter sent with themenuPick message when the user chooses a menu item. The parameter is the same asthe characters that are actually displayed in the menu.

Note: The font and color of a button menu is determined by the button's font and color
properties. However, on Mac OS systems, the font and color of the option menus and
popup menus is controlled by the operating system's settings if the lookAndFeelis set
to "Appearance Manager", rather than by the button's font and color properties.
Enabling and disabling menu items

To enable or disable a menu item in a handler, you can add or remove the ( special
character, but it is generally easier to use the enable menu and disable menu
commands:

enable menuItem 3 of button "My Menu"
disable menuItem 4 of me

These commands simply add or remove the ( special character at the start of the
designated line of the button's contents.

7.13.5 Menu Bars on Unix and Windows Systems
A menu bar is made up of a group of menu buttons, with the menuMode property of
each button set to "pulldown".

Tip: The Menu Builder can automatically create a menu bar for you. To use the Menu
Builder, choose Tools -> Menu Builder.
To create a menu bar by hand without using the Menu Builder:

1. Create a button for each menu, set the style of each button to "menu", and set the
menuMode of the button to "pulldown". You can either set these properties in a handler,
or simply choose Object -> New Control Pulldown Menu to create each button.
2. Put the menu items into each button's contents. In each button's script, create amenuPick handler to perform whatever actions you want to do when a menu item is
chosen.
3. Select the buttons and form them into a group, then move the group to the appropriateposition at the top of the window. For Windows systems, set the textFont of the group
to the standard font for Windows menus, "MS Sans Serif".
 
Important: The buttons in your menu bar should not overlap. Overlapping buttons may
cause unexpected behavior when the user tries to use a menu.
7.13.6 Menu Bars on Mac OS Systems
To create a Mac OS menu bar, you follow the same steps as for a Unix and Windowsmenu bar above. This places a group of buttons, each of whose menuMode property is
set to "pulldown", at the top of your stack window.

Next, you set the menubar property of your stack to the name of the group. This doestwo things: it displays the menus in the menu bar at the top of the screen, and it shortensthe stack window and scrolls it up so that the group of menu buttons is not visible in thewindow. Since the menus are in the menu bar, you don't need to see them in the stack
window as well.

Important: If your stack has more than one card, make sure that the group is placed on
all the cards. (To place a group on a card, choose Object menu Place Group, or use the
place command.) This ensures that the menu bar will be accessible on all cards of the
stack, and prevents the stack from changing size as you move from card to card (toaccommodate shortening the stack window for the menu bar group).
The default menu bar

If other stacks in your application don't have their own menu bars, set thedefaultMenubar global property to the name of your menu group, as well as setting
the stack's menubar property. The defaultMenubar is used for any stack that
doesn't have a menu bar of its own.

Tip: For a custom menu bar to work correctly inside the LiveCode development
environment, you must set the defaultMenubar to the name of your menu group. This
overrides the LiveCode IDE menu bar. You can get the menu bar back by choosing the
pointer tool.
Button menu references

If the button is a button menu that's being displayed in the menu bar, you can use the
word "menu" to refer to it:

get menuItem 2 of menu "Edit"
-- same as 'get line 2 of button "Edit"'

Because menus are also buttons, you can use a button reference to get the sameinformation. But you may need to specify the group and stack the button is in, to avoid
ambiguity. (For example, if there is a standard button named "Edit" on the current card,

 
the expression button "Edit" refers to that button, not to the one in the menu bar.)
An unambiguous button reference to a menu might look like this:

get line 2 of button "Edit" of group "Menu" of stack "Main"

The above statement produces the same information as the form using "menu", but you
need to know the group name and possibly which stack it's in, so the menu
menuNameform is a little more convenient.

The layer of menu buttons

For a menu bar to work properly on Mac OS and OS X systems, the menus must be in
layer order within the group. That is, the button for the File menu must be numbered 1,
the button for the Edit menu must be 2, and so on. The Menu Builder takes care of thisautomatically; you only need to worry about layering if you're creating the menu bar by
hand.

Changing menus dynamically

If you want to dynamically change a menu's contents with a mouseDown handler at the
time the menu is displayed, you must place the mouseDown handler in the group'sscript. When a menu button is being displayed in the Mac OS menu bar, it does notreceive mouseDown messages, but its group does.

The editMenus property

When you set the menubar property of a stack to the name of a group, the stack isresized and scrolled up so the part of the window that holds the menus is not visible. To
reverse this action so you can see, select and edit the buttons that make up your menu bar,
set the editMenus property to true. This resizes the stack window so the button menusare again visible, and you can use the tools in the LiveCode development environment to
make changes to them.

To scroll the stack window again so that the menus are hidden, set the editMenus
property back to false.

Special menu items

A few menu items on Mac OS and OS X are handled directly by the operating system. To
accommodate these special menu items while allowing you to create a fully crossplatform
menu bar, LiveCode treats the last two menu items of the Help menu (for MacOS and OS X), the File menu (OS X), and the Edit menu (OS X) differently.

By following these guidelines, you can make sure your menus will appear properly on alloperating systems without having to write special code or create platform-specific menu
bars.

The Help menu and the "About This Application" menu item

When LiveCode sets up the Mac OS menu bar, it automatically makes the last button theHelp menu (regardless of the button's name). The standard Help menu items, such as

 
"About This Application" and "Show Balloons" on Mac OS Classic, are included for you
automatically; you don't need to include them in your Help menu button, and you can't
eliminate them from the Help menu.

LiveCode moves the last menu item in the Help menu to the "About This Application"
position. On Mac OS systems, this is the first menu item in the Apple menu. On OS Xsystems, it's the first menu item in the Application menu. Therefore, the last menu item in
your Help menu button should be an appropriate "About" item. The menu item above itmust be a divider line (a dash), and above that must be at least one menu item to beplaced in the Help menu.

The File menu and the "Quit" menu item

On OS X systems, the "Quit" menu item is normally placed in the Application menu
(which is maintained by the operating system) rather than in the File menu, as is standard
on other platforms. To accommodate this user-interface standard, LiveCode removes thelast two menu items of the File menu when a standalone application is running on an OSX system. Therefore, the last menu item in your File menu button should be "Quit". Themenu item above it should be a divider line (a dash).

The Edit menu and the "Preferences" menu item

On OS X systems, the "Preferences" menu item is also normally placed in theApplication menu. To accommodate this user-interface standard, LiveCode removes thelast two menu items of the Edit menu when a standalone application is running on an OSX system. Therefore, the last menu item in your Edit menu button should be"Preferences". The menu item above it should be a divider line (a dash).

Note: The Preferences menu item is treated in this special way only if its name starts
with the string "Preferences".
Tip: If your application's user interface is presented in a language other than English, set
the name of the Edit menu button to "Edit", and set its label to the correct translation.
This ensures that the engine can find the Edit menu, while making sure that the menu is
shown in the correct language.
Choosing the special menu items

When the user chooses any of these special menu items, a menuPick message is sent to
the button that the menu item is contained in. This ensures that your button scripts willwork on all platforms, even if LiveCode displays a menu item in a different menu to
comply with user-interface guidelines.

For example, if the user chooses "About This Application" from the Apple menu on aMac OS system, a menuPick message is sent to the Help menu button, with "About

 
This Application" as its parameter. You handle the message for the About menu item in
the Help menu button's script, even though LiveCode displays this menu item in adifferent menu on the Mac.

7.13.7 Stack Menus
Button menus can be used for most kinds of standard menus. However, if you want to
create a menu with a feature that is not supported by button menus--for example, if you
want a popup menu that provides pictures, rather than text, as the choices--you can createa menu from a stack.

Creating a stack menu

To create a stack menu, you create a stack with a control for each menu item. Since thestack menu is a stack and each menu item is an object, the menu items receive mousemessages such as mouseEnter,mouseLeave, and mouseUp.

When the user chooses an item from the stack menu, a mouseUp message is sent to thatcontrol. To respond to a menu item choice, instead of handling the menuPick message,
you can place a mouseUp handler in the script of the object.

To create a stack menu that looks like a standard menu, create a button in the stack for
each menu item. The button's autoArm and armBorder properties should be set to
true. Or you can choose "Menu Item" item in the "New Control" submenu of the Objectmenu to create a button with its properties set to the appropriate values.

Be sure to set the rectangle of the stack to the appropriate size for the menu.
Remember, when you open the menu, the stack will be displayed exactly as it looks in an
editable window.

Finally, either set the menuName property of a button to a reference to the stack, or place
a mouseDown handler containing a pulldown, popup, or option command in the
script of an object. When you click the button or object, the stack menu appears.

Displaying a stack menu

Stack menus can be associated with a button, just like button menus. But when you click
the button, instead of displaying a menu with the button's contents, LiveCode displays astack with the behavior of a menu.

You can also display a stack menu without associating it with a button, by using thepulldown, popup, or option command. Normally, you use these commands in a
mouseDown handler, so that the menu appears under the mouse pointer:

on mouseDown -- in card script

 popup stack "My Menu Panel"
end mouseDown

 
7.13.8 Displaying Context Sensitive Menus
There are also several commands to display a context menu. Usually, you use thesecommands in a mouseDown handler – normally either in your card or stack script:

popup command: opens a stack as a popup menu
pulldown command: opens a stack as a pulldown menu
option command: opens a stack as an option menu


Note: If you set a button's menuName property to the name of a stack, the stack menu
is displayed automatically when the user clicks the button. You need the popup,
pulldown, and option commands only if you want to display a stack menu in some way
other than when a button is clicked.
7.14Searching and Navigating Cards using the Find Command

The find command in LiveCode allows you to search the fields of the current stack, then
navigate to and highlight the results of the search automatically. While it is possible to
build such a command using the comparison features detailed in the chapter Processing
Text and Data, for most purposes the find command provides a complete, pre-built
solution.

find [form] textToFind [in field]

The form can be one of the following:
normal
characters or character (or chars or char)
words or word
stringwhole

If no form is specified, the find normal form is used.

The textToFind is any expression that evaluates to a string.

The field is any expression that evaluates to a field reference. If the field is not specified,
the find command searches all the fields in the current stack (except fields whosedontSearch property is set to true).

find "heart"
find string "beat must go on" in field "Quotes"


When the find command finds a match, it highlights the match on the screen – ifnecessary navigating to the card that contains the match and scrolling the field so the textis in view.

 
The find command can also be used to return the location of the text that was found.
To reset the find command so that it starts searching at the beginning again:

find empty

For more details on the find command and associated options, see the find command in
the LiveCode Dictionary.

7.15Using Drag and Drop

LiveCode allows you complete control over drag and drop – both within LiveCodewindows and between LiveCode and other applications.

7.15.1 Initiating a Drag Drop
To begin a drag and drop operation, the user clicks and holds the mouse pointer. Thissends a mouseDown message to the object.

If you drag from within a field, a dragStart message is sent. To allow drags from alocked field or from another object type, in the object's mouseDown handler, set the
dragData property to the data you want to drag. When there is a value in the
dragData, a drag and drop is initiated when the mouse is clicked and then moved.

set the dragData["text"] to "text being dragged"

You can set the dragData to contain any of the following types of data:

text The plain text being dragged.
HTML The styled text being dragged, in the same format asthe htmlText
RTF The styled text being dragged, in the same format asthe RTFText
Unicode The text being dragged, in the same format as the
unicodeText
image The data of an image (in PNG format)
files The name and location of the file or files being
dragged, one per line

Note: LiveCode automatically handles the mechanics of dragging and dropping text
between and within unlocked fields. To support this type of drag and drop operation, you
don't need to do any scripting.
For more details, see the entries for dragStart and dragData in the LiveCode Dictionary.

 
7.15.2 Tracking During a Drag Drop Operation
You can use the dragEnter message to show an outline around an object or change thecursor when the mouse moves into it during a drag operation.

on dragEnter -- show a green outline around the drop targetset the borderColor of the target to "green"
end dragEnter

You can use the dragMove message to update the screen whenever the cursor movesduring a drag and drop operation.

on dragMove -- in a field script

-- set the cursor so it shows you can only drop onto a linkif the textStyle of the mouseChunk contains "link"
then set the cursor to the ID of image "Drop Here"
else set the cursor to the ID of image "Dont Drop"

end dragMove

You can use the dragLeave message to remove any outline around an object or changethe cursor when the mouse moves out of an object during a drag operation.

on dragLeave
-- remove any outline around the drop no-longer-targetset the borderColor of the target to empty

end dragLeave

For more details, see the entries for dragEnter, dragMove and dragLeave in the LiveCode
Dictionary.

7.15.3 Responding to a Drag and Drop
To perform an action when the user drops data onto a locked field or another object type,
you handle the dragDrop message.

The dragDrop message is sent when the user drops data on an object.

on dragDrop -- check whether a file is being dropped
if the dragData["files"] is empty then beep 2pass dragDrop

end dragDrop

You must set the acceptDrop property to true before a drop will be allowed. Usually,
you set this property to true in a dragEnter handler.

You can use the dragDestination function to retrieve the long id of the object thatthe dragged data was dropped on. You can use the dragSource function to retrieve the
long id of the object that was the source of the drag.

 
When a drag drop has been completed, a dragEnd message is sent to the object the drag
and drop started from.

on dragEnd -- remove data being dragged

delete the dragSourceend dragEnd

You can use the dropChunk function to retrieve the location of the text that was
dropped in a field. For example, you could select the text that was dropped by doing thefollowing:

select the dropChunk

For more details, see the entries for dragDrop, dragEnter, dragDestination, dragEnd,
dragSource , dropChunk and acceptDrop in the LiveCode Dictionary.

7.15.4 Prevent Dragging and Dropping to a Field
You prevent dropping data into a field during a drag and drop by setting theacceptDrop property to false when the mouse pointer enters the field.

If the acceptDrop is set to false, when you drop data, no dragDrop message is sentto the field. Since the drop is automatically processed only when LiveCode receives adragDrop message, this prevents the usual automatic drop behavior.

Usually, you should set the acceptDrop in a dragEnter handler, as in the following
example:

on dragEnter -- in a field script

 set the acceptDrop to falseend dragEnter

If you want to prevent dragging text within a field, intercept the dragStart message:

on dragStart

-- do nothingend dragStart

For more details, see the entries for acceptDrop, dragDrop and dragEnter in the
LiveCode Dictionary.
January 28, 2014, at 04:12 PM by Massimiliano Vessi -
Added lines 1535-1536:
E' possibile dare '''qualsiasi''' forma alle finestre, per esempio un ovale:
Changed lines 1539-1546 from:

7.12.11 Irregularly-Shaped and Translucent Windows
You can set a stack’s windowShape property to the transparent, or alpha channel of an
image that has been imported together with its alpha channel. This allows you to create awindow with "holes" or a window with variable translucency. You can apply a shape
to
any type of stack, regardless of the mode it is opened, allowing such a window to exhibitmodal behavior as a dialog, float as a palette, etc.

You may use either a GIF or PNG image for irregularly shaped windows. If you wanttranslucency you must use PNG images. Translucency is currently only supported on
Windows and Mac OS X systems.
to:
Basta creare un'immagine con delle parti trasparenti (con il formato PNG), poi caricarla nel programma con il comando ''File->Import as Control->Image file''', e infine vedere l'ID assegnato da Livecode all'immagine importata. Fatto cio' basta impostare la proprieta' '''windowshape''' all'ID dell'imagine, esempio:
 set the windowshape of this stack
to ID 1008

January 28, 2014, at 04:07 PM by Massimiliano Vessi -
Changed lines 1525-1674 from:



7.12.7 Window Types and the Mode Property
In a script, you can find out a stack window's type by checking the stack's mode
property. This read-only property reports a number that depends on the window type. Forexample, the mode of an editable window is 1, and the mode of a palette is 4.

You can use the mode property in a script to check what sort of window a stack is being
displayed in:

if the mode of this stack is 5 then -- modal dialog box
close this stack
else -- some other type of windowbeepend if

For complete information about the possible values of the mode property, see its entry in
the LiveCode Dictionary.

 
7.12.8 Window Appearance
Details of a window's appearance, such as the height of its title bar and the background
color or pattern in the window itself, are mainly determined by the stack's mode. Thereare a few additional elements of window appearance that you can control with specificproperties.

The metal property

On OS X systems, you use a stack's metal property to give the stack window a textured
metal appearance. This metal appearance applies to the stack's title bar and itsbackground.

Tip: The metal appearance, in general, should be used only for the main window of an
application, and only for windows that represent a physical media device such as a CD
player. See Apple's Aqua user-interface guidelines for more information.
Window background color

The background color or pattern of a window's content area--the part that isn't part of thetitle bar--is determined by the window type and operating system, by default. For
example, on OS X systems, a striped background appears in palettes and modeless dialog
boxes.

If you want a window to have a specific color or pattern, you can set the stack'sbackgroundColoror backgroundPattern property:

set the backgroundColor of stack "Alpha" to "aliceblue"
set the backgroundPattern of stack "Beta" to 2452 -- img ID

This color or pattern overrides the usual color or background pattern.

7.12.9 The Decorations Property
Most of the properties that pertain to a window's appearance can also be set in the stack's
decorations property. The decorations of a stack consists of a comma-separated
list of decorations:

set the decorations of stack "Gamma" to "title,minimize"

The statement above sets the stack'sminimizeBox property to true, as well as showing
its title bar, and sets other stack properties (maximizeBox, closeBox, metal) to
false. Conversely, if you set a stack's minimizeBox property to true, its
decorations property is changed to include "minimize" as one of its items. In this
way, the decorations property of a stack interacts with its closeBox,
minimizeBox, zoomBox, metal, shadow, and systemWindow properties.

The decorations property and menu bars in a window

 
On Unix and Windows systems, the menu bar appears at the top of the window. On thesesystems, whether a window displays its menu bar is determined by whether the stack'sdecorations property includes "menu":

set the decorations of this stack to "title,menu"

On Mac OS and OS X systems, the menu bar appears at the top of the screen, outside any
window. On these systems, the "menu" decoration has no effect.

Title bar

The user drags the title bar of a window to move the window around the screen. In
general, if the title bar is not displayed, the user cannot move the window. You use thedecorations property (discussed below) to hide and show a window's title bar.

When the user drags the window, LiveCode sends a moveStack message to the current
card.

The decorations property affects only whether the window can be moved by
dragging it. Even if a stack's decorations property does not include the title bar
decoration, you can still set a stack's location, rectangle, and related properties to
move or resize the window.

Window title

The title that appears in the title bar of a window is determined by the stack's label
property. If you change a stack's label in a script, the window's title is immediately
updated.

If the label is empty, the title bar displays the stack's name property. (If the stack is in
an editable window whose cantModify is false, an asterisk appears after the windowtitle to indicate this, and if the stack has more than one card, the card number also appearsin the window title. These indicators do not appear if the stack has alabel.)

Because the window title is determined by the stack's label property instead of its
name property, you have a great deal of flexibility in changing window title. Your scriptsrefer to the stack by its name--which doesn't need to change--not its label, so you can
change the window title without changing any scripts that refer to the stack.

The close box

The close box allows the user to close the window by clicking it. To hide or show theclose box, you set the stack's closeBox property:

set the closeBox of stack "Bravo" to false

When the user clicks the close box, LiveCode sends a closeStackRequest message,
followed by a closeStack message, to the current card.

 
The closeBox property affects only whether the window can be closed by clicking.
Even if a stack's closeBox property is false, you can still use the close command in a
handler or the message box to close the window.

The minimize box or collapse box

The terminology and behavior of this part of the title bar varies depending on platform.
On Mac OS systems, the collapse box shrinks the window so only its title bar is shown.
The minimize box (OS X and Windows systems) or iconify box (Unix systems) shrinksthe window to a desktop icon.

To hide or show the minimize box or collapse box, you set the stack's minimizeBox
property:

set the minimizeBox of this stack to true

that appears when the stack is minimized.
Tip: On OS X and Unix systems, you can set a stack's icon property to specify the icon

When the user clicks the minimize box or collapse box, LiveCode sends an
iconifyStack message to the current card.

The maximize box or zoom box

The terminology and behavior of this part of the title bar varies depending on platform.
On Mac OS and OS X systems, the zoom box switches the window between its currentsize and maximum size. The maximize box (Unix and Windows systems) expands thewindow to its maximum size.

To hide or show the zoom box or maximize box, you set the stack's zoomBox property:

set the zoomBox of stack "Hello" to false

When the user clicks the zoom box or maximize box, LiveCode sends a resizeStack
message to the current card.

7.12.10 Making a stack resizable
A stack's resizable property determines whether the user can change its size by dragging
a corner or edge (depending on operating system) of the stack window.

Tip: To move and resize controls automatically to fit when a stack is resized, use the"Geometry" pane in the control's property inspector.
 
Some stack modes cannot be resized, regardless of the setting of the stack's resizable
property. Modal dialog boxes, sheets, and drawers cannot be resized by the user, and do
not display a resize box.

The resizable property affects only whether the window can be resized by dragging acorner or edge. Even if a stack's resizable property is set to false, you can still set a
stack's location, rectangle, and related properties to move or resize the window.

When the user resizes a stack, LiveCode sends a resizeStack message to the current card.
to:
!!Pulsanti del titolo
Potete anche indicare i pulsanti che debbono apparire nella finestra, basta indicarli con una serie di valori divisi dalla virgola, esempio:
 set the decorations of stack "Gamma" to "title,minimize"

!!Finestre ridimensionabili
Per impedire o permettere di ridimensionare una finestra, basta impostare la proprieta' '''resizable''' su ''true'' o ''false'':
 set the resizable of this stack to false

!!Finestre irregolari o semitrasparenti

Attach:LCTransparentWindow.jpg


7.12.11 Irregularly-Shaped and Translucent Windows
You can set a stack’s windowShape property to the transparent, or alpha channel of an
image that has been imported together with its alpha channel. This allows you to create awindow with "holes" or a window with variable translucency. You can apply a shape to
any type of stack, regardless of the mode it is opened, allowing such a window to exhibitmodal behavior as a dialog, float as a palette, etc.

You may use either a GIF or PNG image for irregularly shaped windows. If you wanttranslucency you must use PNG images. Translucency is currently only supported on
Windows and Mac OS X systems.

7.13Programming Menus & Menu Bars

Menus in LiveCode are not a separate object type. Instead, you create a menu from either
a button or a stack, then use special commands to display the menu or to include it in amenu bar.

This topic discusses menu bars, menus that are not in the menu bar (such as contextualmenus, popup menus, and option menus), how to make menus with special features such
as checkmarks and submenus, and how to use a stack window as a menu for total control
over menu appearance.

To easily create menu bars that work cross-platform, choose Tools -> Menu Builder.
See the section on the Menu Builder in the chapter on Building a User interface for more
details. The details about menu bars in this topic are needed only if you want edit menu
bars by script, for example if you want to include specific features not supported by theMenu Builder.

7.13.1 Menu Types
LiveCode supports several menu types: pulldown menus, option menus (usually called
popup menus on Mac OS and OS X), popup menus (usually called contextual menus on
Mac OS and OS X), and combo boxes.

Each of these menu types is implemented by creating a button. If the button's styleproperty is set to "menu", clicking it causes a menu to appear. The button's menuMode
property determines what kind of menu is displayed.

January 28, 2014, at 11:52 AM by Massimiliano Vessi -
Changed lines 1514-2375 from:


7.9 Custom Property Sets
Custom properties can be organized into custom property sets – or arrays of customproperties. A custom property set is a group of custom properties that has a name you
specify.

When you refer to a custom property, LiveCode looks for that property in the object's
currently-active custom property set. When you create or set a custom property,
LiveCode creates it in the currently-active custom property set, or sets the value of thatproperty in the currently-active set. One custom property set is active at any one time, butyou can use array notation to get or set custom properties in sets other than the currentset.

The examples in the previous section assume that you haven't created any customproperty sets. If you create a custom property without creating a custom property set for
it, as shown in the previous examples, the new custom property becomes part of theobject's default custom property set.

7.9.1 Creating custom property sets
To make a custom property set active, you set the object's customPropertySetproperty to the set you want to use. As with custom properties and local variables, if thecustom property set you specify doesn't exist, LiveCode automatically creates it, so you
can create a custom property set for an object by simply switching to that set.

The following statement creates a custom property set called "Alternate" for an object,
and makes it the active set:

set the customPropertySet of the target to "Alternate"

The statement above creates the custom property set.

You can also view, create, and delete custom property sets in the Custom pane of theobject's property inspector.

You can list all the custom property sets of an object using its customPropertySetsproperty.

As with custom properties, you can create custom property sets for any object. But you
can't create global custom property sets, or custom property sets for a chunk of a field.

 
7.9.2 Custom property set names
The names of custom property sets should consist of a single word, with any combination
of letters, digits, and underscores (_). The first character should be either a letter or an
underscore.

It is possible to create a custom property set with a name that has more than one word, or
that otherwise doesn't conform to these guidelines. However, this is not recommended,
because such a custom property set can't be used with the array notation described below.

Note: When you use the Custom Properties pane in the property inspector to create a
custom property set, the pane restricts you to these guidelines.
7.9.3 Referring to custom property sets
To switch the active custom property set, set the object's customPropertySet property to
the name of the set you want to use:

set the customPropertySet of button 3 to "Spanish"

Any references to custom property refer to the current custom property set. For example,
suppose you have two custom property sets named "Spanish" and "French", and theFrench set includes a custom property called "Paris" while the Spanish set does not. Ifyou switch to the Spanish set, the customKeys of the object does not include "Paris",
because the current custom property set doesn't include that property.

If you refer to a custom property that isn't in the current set, the reference evaluates to
empty. If you set a custom property that isn't in the current set, the custom property iscreated in the set. You can have two custom properties with the same name in differentcustom property sets, and they don't affect each other: changing one does not change theother.

The customProperties property of an object includes only the custom propertiesthat are in the current custom property set. To specify the customProperties of a
particular custom property set, you include the set's name in square brackets:

put the customProperties[mySet] of this card into myArray

7.9.4 Finding out whether a custom property set exists
The customPropertySets property of an object lists the object's custom property
sets, one per line:

answer the customPropertySets of field "My Field"

 
To find out whether a custom property set for an object exists, you check whether it's
listed in the object's customPropertySets. The following statement checks whether
an image has a custom property set called "Spanish":

if "Spanish" is among the lines of the \
customPropertySets of image ID 23945 then...

You can also look in the Custom Properties pane of the object's property inspector, which
lists the custom property sets in the "Set" menu halfway down the pane.

7.9.5 The default custom property set
An object's default custom property set is the set that's active if you haven't used the
customPropertySet property to switch to another set. Every object has a defaultcustom property set; you don't need to create it.

If you create a custom property without first switching to a custom property set – as in
the earlier examples in this topic – the custom property is created in the default set. If you
don't set the customPropertySet property, all your custom properties are created in
the default set.

The default custom property set has no name of its own, and is not listed in the object's
customPropertySets property. To switch from another set to the default set, you set
the object's customPropertySet to empty:

set the customPropertySet of the target to empty

7.9.6 Using multiple custom property sets
Since only one custom property set can be active at a time, you can create separatecustom properties with the same name but different values in different sets. Which valueyou get depends on which custom property set is currently active.

A translation example

Suppose your stack uses several custom properties that hold strings in English, to bedisplayed to the user by various commands. Your stack might contain a statement such asthis:

answer the standardErrorPrompt of this stack

The statement above displays the contents of the custom property called
"standardErrorPrompt" in a dialog box.

Suppose you decide you want to translate your application into French. To do this, you
make your original set of English custom properties into a custom property set (which
you might call "myEnglishStrings"), and create a new set called "myFrenchStrings" to
hold the translated properties.

 
Each set has the same-named properties, but the values in one set are in French and theother in English. You switch between the sets depending on what language the user
chooses. The statement:

answer the standardErrorPrompt of this stack

provides either the English or French, depending on which custom property set is active:
"myEnglishStrings" or "myFrenchStrings".

7.9.7 Copying custom properties between property sets
When it's created, a custom property set is empty, that is, there aren't any customproperties in it. You put custom properties into a new custom property set by creating thecustom properties while the set is active:

-- create new set and make it active:
set the customPropertySet of button 1 to "MyNewSet"
-- now create a new custom property in the current set:
set the myCustomProp of button 1 to true

You can also use the customProperties property (which was discussed earlier in
this topic) to copy custom properties between sets. For example, suppose you havecreated a full set of custom properties in a custom property set called
"myEnglishStrings", and you want to copy them to a new custom property set,
"frenchStrings", so you can translate them easily. The following statements create thenew custom property set, then copy all the properties from the old set to the new one:

-- create the new set:
set the customPropertySet of this stack to "frenchStrings"
-- copy the properties in the English set to the new set:
set the customProperties["frenchStrings "] of this \


 stack to the customProperties["frenchStrings "] \

 of this stack

Caution: Custom property sets in the development environment
The LiveCode development environment uses custom properties to create much of its
own user interface. All these properties are stored in custom property sets whose names
start with "cRev".
If you're creating custom properties, but not organizing them into your own custom
property sets, you don't need to worry about LiveCode's custom properties. Unless youchange an object's customPropertySet, your handlers will never interact withthem.
 
However, if you are using custom property sets--for example, if you have a repeatloop that goes through all of an object's custom property sets--be sure to skip any whose
names start with "cRev". This ensures that you won't accidentally interfere with any ofLiveCode's reserved custom properties.
7.9.8 Arrays, custom properties, and custom property sets
All the custom properties in a custom property set form an array. The array's name is thecustom property set name, and the elements of the array are the individual customproperties in that custom property set.

Referring to custom properties using array notation

You can use array notation to refer to custom properties in any custom property set. Thislets you get and set any custom property, even if it's not in the current set, without
changing the current set.

For example, suppose a button has a custom property named "myProp" which is in acustom property set called "mySet". If "mySet" is the current set, you can refer to the"myProp" property like this:

get the myProp of button 1set the myProp of the target to 20

But you can also use array notation to refer to the "myProp" property, even if "mySet" isnot the current set. To refer to this custom property regardless of which custom property
set is active, use statements like the following:

get the mySet["myProp"] of button 1set the mySet["myProp"] of the target to 20

Note: Because the default custom property set has no name, you cannot use array
notation to refer to a custom property in the default set.
Storing an array in a custom property set

If you store a set of custom properties in a custom property set, the set can be used justlike an array. You can think of the custom property set as though it were a single customproperty, and the properties in the set as the individual elements of the array.

To store an array variable as a custom property set, use a statement like the following:

set the customProperties["myProperty"] of me to theArray

 
The statement above creates a custom property set called "myProperty", and stores each
element in "theArray" as a custom property in the new set. To retrieve a single element ofthe array, use a statement like this:

get the myProperty["myElement"] of field "Example"

7.9.9 Deleting a custom property set
As described above, the customPropertySets property of an object is a list of the
object's custom property sets. You can set the customPropertySets of an object to
control which custom property sets it has.

In LiveCode, there is no command to delete a custom property set. Instead, you place all
the custom property set names in a variable, delete the one you don't want from thatvariable, and set the customPropertySets back to the modified contents of the
variable. This removes the custom property set whose name you deleted.

For example, the following statements delete a custom property set called "mySet" fromthe button "My Button":

get the customPropertySets of button "My Button"
set the wholeMatches to true
delete line lineOffset("mySet",it) of itset the customPropertySets of button "My Button" to it

You can also delete a custom property set in the Custom Properties pane of the object's
property inspector. Select the set's name from the Set menu, then click the Delete button
to remove it.

7.10Attaching Handlers to Custom Properties

When you change a custom property, LiveCode sends a setProp trigger to the object
whose property is being changed. You can write a setProp handler to trap this trigger
and respond to the attempt to change the property. Like a message, this trigger uses themessage path, so you can place the setProp handler anywhere in the object's message
path.

Similarly, when you get the value of a custom property, LiveCode sends a getProp call
to the object whose property is being queried. You can write a getProp handler to reply
to the request for information. Like a function call, the getProp call also traverses the
message path.

Using getProp and setProp handlers, you can:

*
validate a custom property's value before setting it
*
report a custom property's value in a format other than what it's stored as
*
ensure the integrity of a collection of properties by setting them all at once
*
change an object's behavior when a custom property is changed
 
Note: setProp triggers and getProp calls are not sent when a built-in property is
changed or accessed. They apply only to custom properties.
7.10.1 Responding to changing a custom property
When you use the set command to change a custom property, LiveCode sends a
setProp trigger to the object whose property is being changed.

A setProp trigger acts very much like a message does. It is sent to a particular object.
If that object's script contains a setProp handler for the property, the handler isexecuted; otherwise, the trigger travels along the message path until it finds a handler for
the property. If it reaches the end of the message path without being trapped, thesetProp trigger sets the custom property to its new value. For more information aboutthe message path, see the section on the Message Path.

You can include as many setProp handlers in a script for as many different custom
properties as you need.

7.10.2 The structure of a setProp handler
Unlike a message handler, a setProp handler begins with the word setProp instead of
the word on. This is followed by the handler's name (which is the same as the name ofthe custom property) and a parameter that holds the property's new value. A setProp
handler, like all handlers, ends with the word "end" followed by the handler's name.

The following example shows a setProp handler for a custom property named
"percentUsed", and can be placed in the script of the object whose custom property it is:

setProp percentUsed newAmount

-- responds to setting the percentUsed property

 if newAmount is not a number \

 or newAmount < zero or newAmount > 100 then

 beep 2

exit percentUsed

end if

 pass percentUsedend percentUsed

When you set the "percentUsed" custom property, the "percentUsed" handler is executed:

set the percentUsed of scrollbar "Progress" to 90

When this statement is executed, LiveCode sends a setProp trigger to the scrollbar.
The new value of 90 is placed in the newAmount parameter. The handler makes sure thatthe new value is in the range 0–100; if not, it beeps and exits the handler, preventing theproperty from being set.

 
For more details about the setProp control structure, see setProp in the LiveCode
Dictionary.

Passing the setProp trigger

When the setProp trigger reaches the engine--the last stop in the message path--thecustom property is set. If the trigger is trapped and doesn't reach the engine, the customproperty is not set.

To let a trigger pass further along the message path, use the pass control structure. The
pass control structure stops the current handler and sends the trigger on to the next objectin the message path, just as though the object didn't have a handler for the customproperty.

In the "percentUsed" handler above, if the newAmount is out of range, the handler uses
the exit control structure to halt; otherwise, it executes the pass control structure. If the
newAmount is in the right range, the pass control structure lets the property be set.
Otherwise, since the trigger is not passed, it never reaches the engine, so the property isnot changed.

You can use this capability to check the value of any custom property before allowing itto be set. For example, if a custom property is supposed to be boolean (true or false), asetProp handler can trap the trigger if the value is anything but true or false:

setProp myBoolean newValue

 if newValue is true or newValue is false

 then pass myBooleanexit myBoolean

Using the message path with a setProp trigger

Because setProp triggers use the message path, a single object can receive the
setProp triggers for all the objects it owns. For example, setProp triggers for all
controls on a card are sent to the card, if the control's script has no handler for thatproperty. You can take advantage of the message path to implement the same setPropbehavior for objects that all have the same custom property.

Caution: If a setProp handler sets its custom property, for an object that has that
setProphandler in its message path, a runaway recursion will result. To avoid thisproblem, set the lockMessages property to true before setting the custom property.
For example, suppose that all the cards in your stack have a custom property named
"lastChanged". Instead of putting a setProp handler for this property in the script of each
card, you can put a single handler in the stack script:
 
setProp lastChanged newDateconvert newDate to seconds
lock messages -- prevent recursionset the lastChanged of the target to newDateunlock messagesend lastChanged
Note: To refer to the object whose property is being set, use the target function. The
target refers to the object that first received the setProp trigger--the object whose
custom property is being set--even if the handler being executed is in the script of another
object.
Setting properties within a setProp handler

In the "lastChanged" example in the box above, the handler sets the custom property
directly, instead of simply passing the setProp trigger. You must use this method if thehandler makes a change to the property's value, because the pass control structure
simply passes on the original value of the property.

Important: If you use the setcommand within a setProphandler to set the same
custom property for the current object, no setProptrigger is sent to the target object.
(This is to avoid runaway recursion, where the setProp handler triggers itself.) Setting
a different custom property sends a setProp trigger. So does setting the handler's
custom property for an object other than the one whose script contains the setProphandler.
Using this method, you can not only check the value of a property, and allow it to be setonly if it's in range, you can also change the value so that it is in the correct range, has thecorrect format, and so on.

The following example is similar to the "percentUsed" handler above, but instead ofbeeping if the newAmount is out of range, it forces the new value into the range 0–100:

setProp percentUsed newAmount
set the percentUsed of the target to \
max(zero,min(100,newAmount))
end percentUsed

Nonexistent properties

 
If the custom property specified by a setProp handler doesn't exist, the setProp handler isstill executed when a handler sets the property. If the handler passes the setProptrigger, the custom property is created.

Custom property sets and setProp handlers

A setProp handler for a custom property set behaves differently from a setProp handler
for a custom property that's in the default set.

When you set a custom property in a custom property set, the setProp trigger is named
for the set, not the property. The property name is passed in a parameter using a specialnotation. This means that, for custom properties in a set, you write a single setProp
handler for the set, rather than one for each individual property.

The following example handles setProp triggers for all custom properties in a custom
property set called myFrenchStrings, which contains custom properties named
standardErrorPrompt, filePrompt, and perhaps other custom properties:

setProp myFrenchStrings[myPropertyName] newValue-- The myPropertyName parameter contains the name of-- the property that's being setswitch myPropertyName
case "standardErrorPrompt"

 set the myFrenchStrings["standardErrorPrompt"] \

of the target to return & newValue & return
exit myFrenchStrings
break


 case "filePrompt"
set the myFrenchStrings["filePrompt"] \


 of the target to return& newValue & return
exit myFrenchStrings
break


 default
pass myFrenchStringsend switch
end myFrenchStrings

As you can see from the exit, pass, and end control structures, the name of thissetProp handler is the same as the name of the custom property set that it controls-"
myFrenchStrings". Because there is only one handler for all the custom properties in thisset, the handler uses the switch control structure to perform a different action for each
property that it deals with.

Suppose you change the "standardErrorPrompt" custom property:

set the customPropertySet of this stack to \
"myFrenchStrings"
set the standardErrorPrompt of this stack to field 1

 
LiveCode sends a setProp trigger to the stack, which causes the above handler to
execute. The property you set – "standardErrorPrompt" – is placed in the"myPropertyName" parameter, and the new value--the contents of field 1 – is placed in
the "newValue" parameter. The handler executes the case for "standardErrorPrompt",
putting a return character before and after the property before setting it.

If you set a custom property other than "standardErrorPrompt" or "filePrompt" in the"myFrenchStrings" set, the default case is executed. In this case, the pass control
structure lets the setProp trigger proceed along the message path, and when it reachesthe engine, LiveCode sets the custom property.

Note: As mentioned above, you can address a custom property in a set either by firstswitching to that set, or using array notation to specify both set and property. The
following example:
set the customPropertySet of me to "mySet"
set the myProperty of me to true
is equivalent to:
set the mySet["myProperty"] of me to true
Regardless of how you set the custom property, if it is a member of a custom property
set, the setProp trigger has the name of the set--not the custom property itself--and you
must use a setProp handler in the form described above to trap the setProp trigger.

7.10.3 Responding to a request for the value of a custom property
When you use a custom property in an expression, LiveCode sends a getProp call to theobject whose property's value is being requested.

A getProp call acts very much like a custom function call. It is sent to a particular object.
If that object's script contains a getProp handler for the property, the handler isexecuted, and LiveCode substitutes the value it returns for the custom property reference.
Otherwise, the call travels along the message path until it finds a handler for the property.
If the getProp call reaches the end of the message path without being trapped, LiveCodesubstitutes the custom property's value in the expression.

You can include as many getProp handlers in a script as you need.

The structure of a getProp handler

Unlike a message handler, a getProp handler begins with the word getProp instead of
the word on. This is followed by the handler's name (which is the same as the name ofthe custom property). A getProp handler, like all handlers, ends with the word "end"
followed by the handler's name.

 
The following example is a getProp handler for a custom property named "percentUsed":

getProp percentUsed

global lastAccessTime

put the seconds into lastAccessTime

pass percentUsedend lastChanged

When you use the "percentUsed" custom property in an expression, the handler isexecuted:

put the percentUsed of card 1 into myVariable

When this statement is executed, LiveCode sends a getProp call to the card to retrieve thevalue of the "percentUsed" property. This executes the getProp handler for the property.
The example handler stores the current date and time in a global variable before theproperty is evaluated. For more details, see getProp in the LiveCode Dictionary.

Returning a value from a getProp handler

When the getProp trigger reaches the engine – the last stop in the message path –
LiveCode gets the custom property from the object and substitutes its value in theexpression where the property was used.

To let a trigger pass further along the message path, use the pass control structure. The
pass control structure stops the current handler and sends the trigger on to the nextobject in the message path, just as though the object didn't have a handler for the customproperty.

To report a value other than the value that's stored in the custom property--for example, ifyou want to reformat the value first – you use the return control structure instead of
passing the getProp call. The following example is a getProp handler for a customproperty named "lastChanged", which holds a date in seconds:

getProp lastChanged

get the lastChanged of the target

convert it to long date

return it
end lastChanged

The return control structure, when used in a getProp handler, reports a property valueto the handler that requested it. In the above example, the converted date – not the rawproperty – is what is reported. As you can see from the example, you're not limited to
returning the actual, stored value of the custom property. In fact, you can return any valueat all from a getProp handler.

 
Important: If you use a custom property's value within the property's getProp handler,
no getProp call is sent to the target object. This is to avoid runaway recursion, where thegetProp handler calls itself.
A handler can either use the return control structure to return a value, or use the passcontrol structure to let LiveCode get the custom property from the object.

If the getProp call is trapped before it reaches the engine and no value is returned in thegetProp handler, the custom property reports a value of empty. In other words, a getProp
handler must include either a return control structure or a pass control structure, or
its custom property will always be reported as empty.

Using the message path with a getProp call

Because getProp calls use the message path, a single object can receive the getProp callsfor all the objects it owns. For example, getProp calls for all controls on a card are sent to
the card, if the control's script has no handler for that property. You can take advantage ofthe message path to implement the same getProp behavior for objects that all have the
same custom property.

Caution: If a getProphandler is not attached to the object that has the customproperty and it uses the value of the custom property, a runaway recursion will result. To
avoid this problem, set the lockMessages property to true before getting the custom
property's value.
Nonexistent properties

If the custom property specified by a getProp handler doesn't exist, the getProp handler isstill executed if the property is used in an expression. Nonexistent properties report
empty; getting the value of a custom property that doesn't exist does not cause a script
error.

Custom property sets and getProp handlers

A getProp handler for a custom property set behaves differently from a getProp handler
for a custom property that's in the default set.

When you use the value of a custom property in a custom property set, the getProp call isnamed for the set, not the property. The property name is passed in a parameter using
array notation. This means that, for custom properties in a set, you write a single getProp
handler for the set, rather than one for each individual property.

The following example handles getProp calls for all custom properties in a customproperty set called expertSettings, which contains custom properties named
fileMenuContents, editMenuContents, and perhaps other custom properties:

 
getProp expertSettings[thePropertyName]

-- The thePropertyName parameter contains the name of

-- the property that's being set

switch thePropertyName

 case "fileMenuContents"

 if the expertSettings[fileMenuContents] of the \

target is empty then return "(No items"

else pass expertSettings

break

 case "editMenuContents"

 if the expertSettings[editMenuContents] of the \

 target is empty then return \

the noviceSettings[editMenuContents] of the target

else pass expertSettingsbreak
default
pass expertSettingsend switch
end expertSettings

As you can see from the pass and end control structures, the name of this getProp
handler is the same as the name of the custom property set that it controls –
"expertSettings". Because there is only one handler for all the custom properties in thisset, the handler uses the switch control structure to perform a different action for each
property that it deals with.

Suppose you get the "fileMenuContents" custom property:

set the customPropertySet of button 1 to "expertSettings"
put the fileMenuContents of button 1 into me

LiveCode sends a getProp call to the button, which causes the above handler to execute.
The property you queried – "fileMenuContents" – is placed in the "thePropertyName"
parameter. The handler executes the case for "fileMenuContents": if the property isempty, it returns "(No items". Otherwise, the pass control structure lets the getProp callproceed along the message path, and when it reaches the engine, LiveCode gets thecustom property.

7.11Virtual Properties

A virtual property is a custom property that exists only in a setProp and/or getProphandler, and is never actually set. Virtual properties are never attached to the object.
Instead, they act to trigger setPropor getProp handlers that do the actual work.

When you use the set command with a virtual property, its setProp handler is executed,
but the setProp trigger is not passed to the engine, so the property is not attached to theobject. When you use a virtual property in an expression, its getProp handler returns a

 
value without referring to the object. In both cases, using the property simply executes ahandler.

You can use virtual properties to:

*
Give an object a set of behaviors
*
Compute a value for an object
*
Implement a new property that acts like a built-in property
7.11.1 When to use virtual properties
Because they're not stored with the object, virtual properties are transient: that is, they arere-computed every time you request them. When a custom property depends on other
properties that may be set independently, it's appropriate to use a virtual property.

For example, the following handler computes the current position of a scrollbar as apercentage (instead of an absolute number):

getProp asPercentage -- of a scrollbar
put the endValue of the target \

- the startValue of the target into valueExtent
return the thumbPosition of me * 100 div valueExtent
end asPercentage

The "asPercentage" custom property depends on the scrollbar's thumbPosition,
which can be changed at any time (either by the user or by a handler). Because of this, ifwe set a custom property for the object, it would have to be re-computed every time thescrollbar is updated in order to stay current. By using a virtual property, you can ensurethat the value of the property is never out of date, because the getProp handler recomputes
it every time you call for the "asPercentage" of the scrollbar.

Virtual properties are also useful solutions when a property's value is large. Because thevirtual property isn't stored with the object, it doesn't take up disk space, and only takesup memory when it's computed.

Another reason to use a virtual property is to avoid redundancy. The following handler
sets the width of an object, not in pixels, but as a percentage of the object's owner's
width:

setProp percentWidth newPercentage
set the width of the target to \
the width of the owner of the target \

* newPercentage div 100end percentWidth
Suppose this handler is placed in the script of a card button in a 320-pixel-wide stack. Ifyou set the button's "percentWidth" to 25, the button's width is set to 80, which is 25%
of the card's 320-pixel width. It doesn't make much sense to store an object's
percentWidth, however, because it's based on the object's width and its owner's width.

 
Consider using virtual properties whenever you want to define an attribute of an object,
but it doesn't make sense to store the attribute with the object – because it would beredundant, because possible changes to the object mean it would have to be re-computed
anyway, or because the property is too large to be easily stored.

7.11.2 Handlers for a virtual property
As you can see by looking at the example above, a handler for a virtual property isstructured like a handler for any other custom property. The only structural difference isthat, since the handler has already done everything necessary, there's no need to actually
attach the custom property to the object or get its value from the object. When you set avirtual property or use its value, the setProp trigger or getProp call does not reach
the engine, but is trapped by a handler first.

Virtual property setProp handlers

A setProp handler for an ordinary custom property includes the pass control structure,
allowing the setProp trigger to reach the engine and set the custom property (or else it
includes a set command that sets the property directly). A handler for a virtual property,
on the other hand, does not include the pass control structure, because a virtual property
should not be set. Since the property is set automatically when the trigger reaches the end
of the message path, a virtual property's handler does not pass the trigger.

If you examine an object's custom properties after setting a virtual property, you'll find
that the custom property hasn't actually been created. This happens because thesetProp handler traps the call to set the property; unless you pass the setProp trigger,
the property isn't passed to LiveCode, and the property isn't set.

Virtual property getProp handlers

Similarly, a getProp handler for an ordinary custom property either gets the property'svalue directly, or passes the getProp call so that the engine can return the property'svalue. But in the case of a virtual property, the object doesn't include the property, so thegetProp handler must return a value.

7.11.3 Creating new object properties
You can use virtual properties to create a new property that applies to all objects, or to allobjects of a particular type. Such a property acts like a built-in property, because you can
use it for any object. And because a virtual property doesn't rely on a custom property
being stored in the object, you don't need to prepare by creating the property for each newobject you create: the virtual property is computed only when you use it in an expression.

The following example describes how to implement a virtual property called
"percentWidth" that behaves like a built-in property.

Setting the "percentWidth" property

Suppose you place the "percentWidth" handler described above in a stack script instead
of in a button's script:

 
setProp percentWidth newPercentage
set the width of the target to \
the width of the owner of the target \

* newPercentage div 100end percentWidth
Because setProp triggers use the message path, if you set the "percentWidth" of any
object in the stack, the stack receives the setProp trigger (unless it's trapped by another
object first). This means that if the handler is in the stack's script, you can set the"percentWidth" property of any object in the stack.

If you place the handler in a backscript, you can set the "percentWidth" of any object,
anywhere in the application.

Note: To refer to the object whose property is being set, use the target function. The
target refers to the object that first received the setProp trigger--the object whose
custom property is being set--even if the handler being executed is in the script of another
object.
Getting the "percentWidth" property

The matching getProp handler, which lets you retrieve the "percentWidth" of an object,
looks like this:

getProp percentWidth
return 100 * (the width of the target \
div the width of the owner of the target)
end percentWidth

If you place the handler above in a card button's script, the following statement reportsthe button's width as a percentage:

put the percentWidth of button "My Button" into field 12

For example, if the stack is 320 pixels wide and the button is 50 pixels wide, the button'swidth is 15% of the card width, and the statement puts "15" into the field.

Like the setProp handler for this property, the getProp handler should be placed far
along the message path. Putting it in a stack script makes the property available to allobjects in the stack; putting it in a backscript makes the property available to all objectsin the application.

Limiting the "percentWidth" property

Most built-in properties don't apply to all object types, and you might also want to createa virtual property that only applies to certain types of objects. For example, it's not very

 
useful to get the width of a substack as a percentage of its main stack, or the width of acard as a percentage of the stack's width.

You can limit the property to certain object types by checking the target object's
name:

setProp percentWidth newPercentage

 if word 1 of the name of the target is "stack" \

 or word 1 of the name of the target is "card" \

then exit setProp

 set the width of the target to \

 the width of the owner of the target \

* newPercentage div 100end percentWidth
The first word of an object's name is the object type, so the above revised handler
ignores setting the "percentWidth" if the object is a card or stack.

7.12Managing Windows, Palettes and Dialogs

LiveCode provides complete control over all aspects of window management, including
moving, re-layering, and changing window mode.

7.12.1 Moving a window
Usually, you use either the locationor rectangle property of a stack to move the
stack window.

Thelocation property specifies the center of the stack's window, relative to the top leftcorner of the main screen. Unlike the location of controls, the location of a stack
is specified in absolute coordinates. The following statement moves a stack to the center
of the main screen:

set the location of stack "Wave" to the screenLoc

The rectangle property of a stack specifies the position of all four edges, and can beused to resize the window as well as move it:

set the rectangle of this stack to "100,100,600,200"

Tip: To open a window at a particular place without flickering, set the stack's location or
rectangle property to the desired value either before going to it, or in the stack’s
preOpenStack handler.
 
You can also use associated properties to move a window. Changing a stack's bottomor
top property moves the window up or down on the screen. Changing the leftor
right property moves the window from side to side.

7.12.2 Changing a window's layer
You bring a window to the front by using the go command:

go stack "Alpha"

If the stack is already open, the go command brings it to the front, without changing its
mode.

To find out the layer order of open stack windows, use the openStacks function. This
function lists all open stack windows in order from front to back.

The palette layer

Normally, palette windows float above editable windows and modeless dialog boxes. Apalette will always above a standard window, even if you bring the standard window to
the front. This helps ensure that palettes, which usually contain tools that can be used in
any window, cannot disappear behind document windows. It's also a good reason to makesure you design palette windows to be small, because other windows cannot be moved in
front of them if the palette blocks part of the window.

The system palette layer

System windows--stacks whose systemWindow property is true--float above all other
windows, in every running application. This means that even if the user brings another
application to the front, your application's system windows remain in front of allwindows.

System windows are always in front of other windows, and you cannot change thisbehavior.

7.12.3 The active window
In most applications, commands are applied to the active window. Since LiveCode givesyou the flexibility to use several different window types, not all of which are editable, thecurrent stack is not always the same as the active window. The current stack is the targetof menu choices such as View -> Go Next and is the stack specified by the expressionthis
stack.

For example, executing the find command may have unexpected results if stacks ofdifferent modes are open, because under these conditions, the search may target a stack
that is not the frontmost window.

Finding the current stack

 
The current stack--the stack that responds to commands--is designated by thedefaultStack property. To determine which stack is the current stack, use the
following rules:

1. If any stacks are opened in an editable window, the current stack is the frontmostunlocked stack. (A stack is unlocked if its cantModify property is set to false.)
2. If there are no unlocked stacks open, the current stack is the frontmost locked stack in
an editable window.
3. If there are no stacks open in an editable window, the current stack is the frontmoststack in a modeless dialog box.
4. If there are no editable or modeless windows open, the current stack is the frontmostpalette.
Another way of expressing this set of rules is to say that the current stack is the frontmost
stack with the lowest mode property. You can find out which stack has the lowest mode
using the topStack function.


The topStack function and the defaultStack property:
The defaultStack property specifies which stack is the current stack. By default, the
defaultStack is set to the topStack, although you can change the
defaultStack to any open stack.


The topStack function goes through the open stacks first by mode, then by layer. For
example, if any editable windows are open, the topmost editable window is the
topStack. If there are no editable windows, the topStack is the topmost modeless
dialog box, and so on.


Changing the current stack

To operate on a stack other than the current stack, set the defaultStack property to
the stack you want to target before executing the commands. Usually, thedefaultStack is the topStack, but you can change it if you want to override theusual rules about which window is active.

A note about Unix systems

If your system is set up to use pointer focus rather than click-to-type or explicit focus,
you may experience unexpected results when using LiveCode, since the current stack willchange as you move the mouse pointer. It is recommended that you configure your
system to use explicit focus when using LiveCode or any other applications created in
LiveCode.

7.12.4 Creating a backdrop
For some applications, you may want to create a solid or patterned backdrop behind your
application's windows. This backdrop prevents other applications' windows from being

 
seen – although it does not close those windows – so it's appropriate for applications likea game or kiosk, where the user doesn't need to see other applications and where you
want to keep distractions to a minimum.

Note: In LiveCode Media edition, you cannot turn off the backdrop property.
To create a backdrop, you set the backdrop property to either a valid color reference,
or the ID of an image you want to use as a tiled pattern:

set the backdrop to "#99FF66" -- a color
set the backdrop to 1943 -- an image ID

In the LiveCode development environment, you can create a backdrop by choosing View
-> Backdrop. Use the Preferences dialog box to specify a backdrop color to use.

7.12.5 Open, Closed, and Hidden Windows
Each open stack is displayed in a stack window. A stack can be open without being
visible, and can be loaded into memory without being open.

Hidden stacks

A stack window can be either shown or hidden, depending on the stack's visible
property. This means a window can be open without being visible on the screen.

Tip: To list all open stacks, whether they're visible or hidden, use the openStacks
function.
Loaded stacks

A stack can also be loaded into memory without actually being open. A stack whosewindow is closed (not just hidden) is not listed by the openStacks function. However,
it takes up memory, and its objects are accessible to other stacks. For example, if a closed
stack that's loaded into memory contains a certain image, you can use the image as abutton icon in another stack.

A stack can be loaded into memory without being open under any of the following
conditions:

A handler in another stack referred to a property of the closed stack. This automatically
loads the referenced stack into memory.

The stack is in the same stack file as another stack that is open.

 
The stack was opened and then closed, and its destroyStack property is set to false.
(If the destroyStack property is false, the stack is closed, but not unloaded, when its
window is closed.)

Tip: To list all stacks in memory, whether they're open or closed, use the
revLoadedStacks function.
7.12.6 The states of a stack
A stack, then, can be in any of four states:

Open and visible:The stack is loaded into memory, its window is open, and the window
is visible.

Open and hidden:The stack is loaded into memory, its window is open, but the windowis hidden. The stack is listed in the Window menu and in the Application Browser.

Closed but loaded into memory:The stack is loaded into memory, but its window is not
open and it is not listed by the openStacks function or in the Window menu.
However, its objects are still available to other stacks, and it is listed in the Application
Browser. A stack that is closed but loaded into memory has a mode property of zero.

To remove such a stack from memory, choose Tools -> Application Browser, find the
stack's name, and Control-click it (Mac OS or OS X) or Right-click it (Unix or
Windows) in the Application Browser window and choose "Close and Remove fromMemory" from the contextual menu.

Closed:The stack is not loaded into memory and has no effect on other stacks.
to:
!!Muovere le finestre
Un metodo per muovere le finestre e' impostare la proprieta' '''loc''' (location), che rappresenta il centro della finestra. Per esempio per mettere al centro dello schermo una finserta, basta scrivere:
 set the location of stack "esempio" to the screenLoc

perche' '''screenLoc''' e' il centro dello schermo.

!!Ridimensionare le finestre
Un modo veloce per impostare le dimensioni di una finestra e' dire la posizione dei sue angoli estremi della finestra si usa la proprieta' '''rectangle''', per esempio per metterli al punto (100,100) e (600,200) bastera':

 set the rectangle of this stack to "100,100,600,200"




7.12.7 Window Types and the Mode Property
In a script, you can find out a stack window's type by checking the stack's mode
property. This read-only property reports a number that depends on the window type. Forexample, the mode of an editable window is 1, and the mode of a palette is 4.

You can use the mode property in a script to check what sort of window a stack is being
displayed in:

if the mode of this stack is 5 then -- modal dialog box
close this stack
else -- some other type of windowbeepend if

For complete information about the possible values of the mode property, see its entry in
the LiveCode Dictionary.

January 28, 2014, at 11:19 AM by Massimiliano Vessi -
Changed lines 1509-1737 from:
This ability is particularly useful if you want to create a number of profiles, as shown in
the following example:

on mouseUp

-- creates a profile for each card in the stack

 repeat with thisCard = 1 to the number of cards

set the revProfile of card x to "myNewProfile"
end repeatend mouseUp

The handler above creates a profile called "myNewProfile" for all the cards in the currentstack.

In order for this handler to work, the "Create profiles automatically" option in the"Property Profiles" pane of the Preferences window must be turned on.

You can control this behavior either in Preferences window or using thegRevProfileReadOnly keyword. If you don't want to save property changes when
switching profiles, do one of the following:

Set the gRevProfileReadOnly variable to true:

global gRevProfileReadOnlyput true into gRevProfileReadOnly

In the "Property Profiles" pane of the Preferences window, uncheck the box labeled
"Don't save changes in profile".

The two methods of changing this setting are equivalent: changing thegRevProfileReadOnly variable also changes the preference setting, and vice versa.

For more details, see gRevProfileReadOnly in the LiveCode Dictionary.

 
7.7.5 Adding profile settings in a handler
You can add a property setting to a profile by switching to the profile, then setting theproperty:

set the revProfile of button 1 to "MyProfile"
set the foregroundColor of button 1 to "red"
set the revProfile of button 1 to "Master"

By default, if you change a property and then switch profiles, the property you changed
and its current setting is saved with the profile.

7.8 Custom Properties
A custom property is a property that you create for an object, in addition to its built-in
properties. You can define custom properties for any object, and use them to store any
kind of data.

This topic discusses how to create and use custom properties, and how to organize
custom properties into sets (or arrays). The following section covers how to create virtual
properties and use getProp and setProp handlers to handle custom property
requests.

7.8.1 Using Custom Properties
A custom property is a property that you define. You can create as many customproperties for an object as you want, and put any kind of data into them (even binary
data). You can even store a file in a custom property.

Use a custom property when you want to:

*
associate data with a specific object
*
save the data with the object in the stack file
*
access the data quickly
7.8.2 Creating a Custom Property
You create a custom property by setting the new property to a value. If you set a customproperty that doesn't exist, LiveCode automatically creates the custom property and sets itto the requested value.

This means that you can create a custom property in a handler or the message box, simply
by using the set command. The following statement creates a custom property called
"endingTime" for a button:

set the endingTime of button "Session" to the long time

You can create custom properties for any object. However, you cannot create globalcustom properties, or custom properties for a chunk of text in a field. Unlike some builtin
properties, a custom property applies only to an object.

 
Important: Each object can have its own custom properties, and custom properties arenot shared between objects. Creating a custom property for one object does not create it
for other objects.
7.8.3 The Content of a Custom Property
You set the value of a custom property by using its property name together with the set
command, in the same way you set built-in properties:

set the myCustomProperty of button 1 to false

You can see and change all of an object's custom properties in the Custom Properties
pane of the object's property inspector: click the custom property you want to change,
then enter the new value.

Changing a part of a property

Like built-in properties, custom properties are not containers, so you cannot use a chunk
expression to change a part of the custom property. Instead, you put the property's valueinto a variable and change the variable, then set the custom property back to the newvariable contents:

put the lastCall of this card into myVarput "March" into word 3 of myVarset the lastCall of thisCard to myVar

7.8.4 Custom Property Names
The name of a custom property must consist of a single word and may contain any
combination of letters, digits, and underscores (_). The first character must be either aletter or an underscore.

Avoid giving a custom property the same name as a variable. If you refer to a customproperty in a handler, and there is a variable by the same name, LiveCode uses thecontents of the variable as the name of the custom property. This usually causesunexpected results.

Important: It is important to avoid giving custom properties the same name as existingengine properties unless those properties are only ever accessed in the context of a
custom property set. Unintended effects may result if you attempt to use the name of an
engine property as a custom property.
 
Important: Custom property names beginning with "rev" are reserved for LiveCode's
own custom properties. Naming a custom property with a reserved name may produceunexpected results when working in the development environment.
7.8.5 Referring to Custom Properties
Custom property references look just like built-in property references: the word the, the
property name, the word of, and a reference to the object.

For example, to use a custom property called "lastCall" that belongs to a card, use a
statement like the following:

put the lastCall of this card into field "Date"

Like built-in properties, custom properties are sources of value, so you can get the valueof a custom property by using it in an expression. The property's value is substituted for
the property reference when the statement is executed. For example, if the card's"lastCall" custom property is "Today", the example statement above puts the string
"Today" into the "Date" field.

7.8.6 Nonexistent Custom Properties
Custom properties that don't exist evaluate to empty. For example, if the current card
doesn't have a custom property called "astCall", the following statement empties thefield:

put the lastCall of this card into field "Date" – empty

Note: Referring to a nonexistent custom property does not cause a script error. This
means that if you misspell a custom property name in a handler, you won't get an error
message, so you might not notice the problem right away.
7.8.7 Finding out Whether a Custom Property Exists
The customKeys property of an object lists the object's custom properties, one per line:

put the customKeys of button 1 into field "Custom Props"

To find out whether a custom property for an object exists, you check whether it's listed
in the object's customKeys. The following statement checks whether a player has acustom property called "doTellAll":

if "doTellAll" is among the lines of the customKeys \
of player "My Player" then...

 
You can also look in the Custom Properties pane of the object's property inspector, which
lists the custom properties. See the chapter on Building a User Interface for more details.

7.8.8 Custom Properties & Converting Text Between Platforms
When you move a stack developed on a Mac OS or OS X system to a Windows or Unix
system (or vice versa), LiveCode automatically translates text in fields and scripts into
the appropriate character set. However, text in custom properties is not converted
between the ISO and Macintosh character sets. This is because custom properties can
contain binary data as well as text, and converting them would garble the data.

Characters whose ASCII value is between 128 and 255, such as curved quotes and
accented characters, do not have the same ASCII value in the Mac OS character set and
the ISO 8859-1 character set used on Unix and Windows systems. If such a character isin a field, it is automatically translated, but it's not translated if it's in a custom property.

Because of this, if your stack displays custom properties to the user--for example, if thestack puts a custom property into a field--and if the text contains special characters, itmay be displayed incorrectly if you move the stack between platforms. To avoid thisproblem, use one of these methods:

Before displaying the custom property, convert it to the appropriate character set using
the macToISOor ISOToMac function. The following example shows how to convert acustom property that was created on a Mac OS system, when the property is displayed on
a Unix or Windows system:

if the platform is "MacOS" then

 answer the myPrompt of button 1else

 answer macToISO(the myPrompt of button 1)
end if

Instead of storing the custom property as text, store it as HTML, using the HTMLText
property of fields:

set the myProp of this card to the HTMLText of field 1

Because the HTMLText property encodes special characters as entities, it ensures thatthe custom property does not contain any special characters--only the platformindependent
encodings for them. You can then set a field's HTMLText to the contents of
the custom property to display it:

set the HTMLText of field "Display" \
to the myProp of this card

7.8.9 Storing a file in a custom property
You can use a URL to store a file's content in a custom property:

 
set the myStoredFile of stack "My Stack" \
to URL "binfile:mypicture.jpg"

You restore the file by putting the custom property's value into a URL:

put the myStoredFile of stack "My Stack" \
into URL "binfile:mypicture.jpg"

Because a custom property can hold any kind of data, you can store either text files or
binary files in a custom property. You can use this capability to bundle media files or
other files in your stack.

Many Mac OS Classic files have a resource fork. To store and restore such a file, you can
use the resfile URL scheme to store the content of the resource fork separately.

Tip: To save space, compress the file before storing it:
Tip: set the myStoredFile of stack "My Stack" \
to compress(URL "binfile:mypicture.jpg")
Tip: When restoring the file, decompress it first:
Tip: put decompress(the myStoredFile of stack "My Stack") \
into URL "binfile:mypicture.jpg"
For more information about using URL containers, see the chapter on Working with
Files, URLs and Sockets.

7.8.10 Deleting a custom property
As described above, the customKeys property of an object is a list of the object's
custom properties. You can set the customKeys of an object to control which custom
properties it has.

In LiveCode, there is no command to delete a custom property. Instead, you place all thecustom property names in a variable, delete the one you don't want from that variable,
and set the object's customKeys back to the modified contents of the variable. This
removes the custom property whose name you deleted.

For example, the following statements delete a custom property called
"propertyToRemove" from the button "My Button":

get the customKeys of button "My Button"
set the wholeMatches to true
delete line lineOffset("propertyToRemove",it) of it

 
set the customKeys of button "My Button" to it

You can also delete a custom property in the Custom Properties pane of the object's
Property Inspector. Select the property's name and click the Delete button to remove it.
to:
La stessa opzione sipuo' configurare con il seguente codice (impostare ''true'' o ''false'' a seconda dell'esigenza):

 global gRevProfileReadOnlyput true into gRevProfileReadOnly




7.9 Custom Property Sets
Custom properties can be organized into custom property sets – or arrays of customproperties. A custom property set is a group of custom properties that has a name you
specify.

When you refer to a custom property, LiveCode looks for that property in the object's
currently-active custom property set. When you create or set a custom property,
LiveCode creates it in the currently-active custom property set, or sets the value of thatproperty in the currently-active set. One custom property set is active at any one time, butyou can use array notation to get or set custom properties in sets other than the currentset.

The examples in the previous section assume that you haven't created any customproperty sets. If you create a custom property without creating a custom property set for
it, as shown in the previous examples, the new custom property becomes part of theobject's default custom property set.

7.9.1 Creating custom property sets
To make a custom property set active, you set the object's customPropertySetproperty to the set you want to use. As with custom properties and local variables, if thecustom property set you specify doesn't exist, LiveCode automatically creates it, so you
can create a custom property set for an object by simply switching to that set.

The following statement creates a custom property set called "Alternate" for an object,
and makes it the active set:

set the customPropertySet of the target to "Alternate"

The statement above creates the custom property set.

You can also view, create, and delete custom property sets in the Custom pane of theobject's property inspector.

You can list all the custom property sets of an object using its customPropertySetsproperty.

As with custom properties, you can create custom property sets for any object. But you
can't create global custom property sets, or custom property sets for a chunk of a field.

January 28, 2014, at 11:14 AM by Massimiliano Vessi -
Added lines 1383-1396:

!!Creare o cancellare oggetti

Potete creare oggetti con la parola '''create''', ad esempio:

 create button "Esempio"

potete anche specificare dove usando la parola '''in'''.

Potete cancellare un oggetto con la parola '''delete''':

 delete button "Esempio"

'''delete''' puo' essere usato anche per cancellare lettere, parole, item, ecc., dai testi.
Changed lines 1460-1473 from:
!!Creare o cancellare oggetti

Potete creare oggetti con la parola '''create''', ad esempio:

 create button "Esempio"

potete anche specificare dove usando la parola '''in'''.

Potete cancellare un oggetto con la parola '''delete''':

 delete button "Esempio"

'''delete''' puo' essere usato anche per cancellare lettere, parole, item, ecc., dai testi.

to:

Changed lines 1491-1492 from:
ma attenzione, gli oggetti devono gia' avere quel profilo dentro di loro su cui cambiare, altrimenti rimarrano come sono.
to:
ma attenzione, gli oggetti devono gia' avere quel profilo dentro di loro su cui cambiare, altrimenti rimarrano come sono. 
Changed lines 1499-1503 from:
Per creare un profilo, oltre a farlo graficamente con il ''Properties Inspector'' (e' molto istruttivo farlo, provateci almeno una volta), potete farlo con il codice '''revProfile'''.
to:
Per creare un profilo, oltre a farlo graficamente con il ''Properties Inspector'' (e' molto istruttivo farlo, provateci almeno una volta graficamente), potete farlo con il codice '''revProfile'''. Ma solo se avete attivato la voce '''Create profiles automatically''' nel pannello delle preferenze:

Attach:LCPrefProfiles.jpg

Questo perche' il comando per creare un nuovo profilo non c'e' e quindi bisogna utilizzare quello per impostare il profilo. Per evitare confusioni o problemi, di solito, quando si imposta un profilo che non esiste, non succede nulla, mentre con questa opzione attiva si crea un nuovo profilo:
January 24, 2014, at 06:20 PM by Massimiliano Vessi -
Changed line 268 from:
* '''premendo il tasto TAB della tastiers si sistema tutto il codice da solo con la giusta indentazione!'''
to:
* '''premendo il tasto TAB della tastiera si sistema tutto il codice da solo con la giusta indentazione!'''
January 24, 2014, at 06:19 PM by Massimiliano Vessi -
Added line 268:
* '''premendo il tasto TAB della tastiers si sistema tutto il codice da solo con la giusta indentazione!'''
January 24, 2014, at 06:16 PM by Massimiliano Vessi -
Changed line 93 from:
Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial" che costa $ 500 anno.  Dopo aver immesso la chiave della licenza del programma, Livecode diventera' COMMERCIAL per un anno, poi tornera' COMMUNITY.
to:
Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial" che costa $ 500 anno.  Dopo aver immesso la chiave della licenza del programma, Livecode diventera' COMMERCIAL per un anno, poi tornera' COMMUNITY. Questo non vuol dire che i vostri programmi durino solo un anno, i vostri programmi creati con Livecode COMMERCIAL saranno sempre closed source. Il termine della licenza influenza solo l'ambiente di sviluppo per creare nuovi programmi o nuove versioni del programma.
January 24, 2014, at 02:18 PM by Massimiliano Vessi -
Changed lines 91-92 from:
Come gia' detto Livecode e' gratuito, ma la versione gratuita non permette di chiudere il codice e renderlo illeggibile (closed source). Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial" che costa $ 500. La licenza commercial '''dura tutta la vita''' e vi permette di scaricare gli aggiornamenti per un anno dall'acquisto.
to:
Come gia' detto Livecode e' gratuito, ma la versione gratuita non permette di chiudere il codice e renderlo illeggibile (closed source).

Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial" che costa $ 500 anno.  Dopo aver immesso la chiave della licenza del programma, Livecode diventera' COMMERCIAL per un anno, poi tornera' COMMUNITY.
Changed lines 1488-1520 from:
The statement above sets the profile of all objects on the current card of the stack named
"My Stack"
. (Although the revSetCardProfile command changes a card, you
specify a stack name, not a card name.)

If an object on the card does not have a profile with the specified name, the object is leftuntouched.

Switching all the objects in
a stack

To switch the profiles of all the objects in a stack
, use the revSetStackProfile
command:

revSetStackProfile "MyProfile","My Stack"

The statement above sets
the profile of all objects in the stack named "My Stack". 

If an object in the stack does not have a profile with the specified name, the object is leftuntouched.

Switching all the objects in a stack file

To switch the profiles of all the objects in every stack in a stack file, use therevSetStackFileProfile command:

revSetStackFileProfile "MyProfile","My Stack"

The statement above sets the profile of all objects in the stack named "My Stack", along
with any other stacks in the same stack file.

 
If an object in any of the stacks does not have a profile with the specified name, theobject is left untouched.

7.7.4 Creating a profile in a handler
In addition to creating property profiles in the property inspector, you can create a profilein a handler.

To enable creating profiles, check the "Create profiles automatically" box in the"Property Profiles" pane of the Preferences window. If this box is checked, setting therevProfile property of an object automatically creates the profile.
to:
ma attenzione, gli oggetti devono gia' avere quel profilo dentro di loro su cui cambiare, altrimenti rimarrano come sono.

Per cambiare tutti gli oggetti di uno stack su un profilo si usa il comando '''revSetStackProfile ''', cosi':

 revSetStackProfile "Profilo1","MioStack"

ma attenzione, gli oggetti devono gia' avere quel profilo dentro di loro su cui cambiare, altrimenti rimarrano come sono.

Per creare un profilo, oltre
a farlo graficamente con il ''Properties Inspector'' (e' molto istruttivo farlo, provateci almeno una volta), potete farlo con il codice '''revProfile'''.

 set
the revProfile of button "bottoneEsempio" to "NuovoProfilo"

tutto qua
.
January 24, 2014, at 12:24 PM by Massimiliano Vessi -
Added lines 88-93:

! Licenze

Come gia' detto Livecode e' gratuito, ma la versione gratuita non permette di chiudere il codice e renderlo illeggibile (closed source). Se siete uno sviluppatore che vuole rendere il proprio codice inaccessibile, e' possibile comprare la versione "commercial" che costa $ 500. La licenza commercial '''dura tutta la vita''' e vi permette di scaricare gli aggiornamenti per un anno dall'acquisto.

Per le aziende e infrastrutture molto grandi, che hanno bisogno di supporto telefonico, corsi specifici e soluzioni in 24 ore e' possibile acquistare licenze annuali dai costi piu' alti che garantiscono del personale dedicato per 12 mesi.
January 23, 2014, at 05:29 PM by Massimiliano Vessi -
Changed lines 1476-1485 from:


set the revProfile of player "My Player" to "MyProfile"

Switching all the objects on a card

To switch the profiles of all the objects on a card, use the revSetCardProfile
command:

revSetCardProfile "MyProfile","My Stack"
to:
La cosa interessante per i profili, che e' possibili applicarli a tutti gli oggetti della carta corrente di una finestra. In questo modo e' molto piu' semplice cambiare le proprieta di tutti gli oggetti in un attimo. Per fare questo e' necessario usare il comando '''revSetCardProfile''' cosi':

 revSetCardProfile "Profilo1","StackdellaFinestra"  #bisogna indicare lo stack, non la carta
January 23, 2014, at 05:24 PM by Massimiliano Vessi -
Changed lines 1473-1510 from:
7.7 Property Profiles
A property profile is a collection of object property settings, which is stored as a set. Aprofile for an object can contain settings for almost any properties of the object.

You can include values for most built-in properties in a profile, and create as many
different property profiles as you need for any object. Once you've created a profile, you
can switch the object to the profile to change all the property values that are defined in
the profile.

For example, suppose you create a property profile for a field that includes settings for
the field's color properties. When you switch to that profile, the field's colors change,
while all other properties (not included in the profile) remain the same.

Use property profiles when you want to:
Create "skins" for your applicationDisplay your application in different languagesPresent different levels--"novice","expert", and so onUse different user-interface standards for different platforms

For details on how to create property profiles using the IDE, see the section on Property
Profiles in the chapter Building a User Interface.

7.7.1 Profile names
Profile names follow the same rules as variable names. A profile name must be a singleword, consisting of letters, digits, and underscores, and must start with either a letter or
an underscore.
Tip: If you want to use a single command to switch several objects to a particular profile,
give the profile the same name for each of the objects it applies to.
7.7.2 The master profile
Every object has a master profile that holds the default settings for all its properties. Ifyou don't set an object's profile, the master profile is used. When you create a newprofile, you can change settings for various properties to make them different from themaster profile's settings.

 
If you don't specify a property setting in a profile, the master profile's setting is used, so
you don't have to specify all properties of an object when you create a profile--only theones you want to change.

By default, the master profile is named "Master". You can change the master profile's
name in the Property Profiles pane of the Preferences window.

7.7.3 Switching between profiles
Switching a single object

To switch an object's profile, you can use either the object's property inspector or the
revProfile property.
to:
I profili servono per memorizzare tutta una serie di proprieta' di un oggetto e cambiarle tutte insieme. Tipicamente sono utilizzate per cambiare lalingua del programma o per personalizzare l'interfaccia come le "skin" dei programmi. Il profilo '''Master''' e' quello di partenza. Il profilo e' sempre memorizzato nella proprieta' '''revProfile'''. Se abbiamo un profilo per un pulsante chiamato ''Profilo1'' bastera' scrivere:
 set the revProfile of button "esempio" to "Profilo1"

January 23, 2014, at 12:53 PM by Massimiliano Vessi -
Changed lines 1451-1501 from:


7.5.3 Creating Objects Off-screen Using Template Objects
LiveCode uses template objects to allow you to specify the properties for an object beforeit is created. The template objects are off-screen models – there is one for each possibletype of object, e.g. button, field, graphic, etc.

If you need to create a new object and then set some properties on the object, it is moreefficient to make the changes to the template object, then create the object. Because theobject can be created with all of its properties set correctly, there is no need to lock thescreen and update or reposition the object after creating it. For example, the LiveCodedevelopment environment uses the template objects internally to create new objects fromthe main tool palette.

 
You set properties on template objects in the same way you set properties on normalobjects.

set the {property} of the template{Objecttype} to {value}

For example, to create a button with the name "Hello World", positioned at 100,100:

set the name of the templateButton to "Hello World"
set the location of the templateButton to 100,100create button

When you have used the templateObject to create a new object, you should reset it beforeusing it again. Resetting the templateObject sets all off its properties back to defaults.

reset the template[Objecttype]

For example, to reset the templateButton:
reset the templateButton

For more details on the template objects, search the LiveCode Dictionary for "template".

7.6 Property Arrays using the Properties Property
In addition to retrieving individual object properties, you can retrieve or set an entire setas an array using the properties property. You can use this to edit, copy, export or
import properties.

set the properties of object to propertiesArrayput the properties of object into propertiesArray

The properties of an object is an array containing that object's significant built-in
properties.

put the properties of button 1 into myArrayset the properties of last player to the properties \

of player "Example"

Tip: This example handler shows you how to write the properties of an object to a text
file.
Tip: on mouseUpput the properties of button 1 into tPropertiesArray
combine tPropertiesArray using return and "|"
ask file "Save properties as:"
if it is not empty then put tPropertiesArray into \
 
URL ("file:" & it)
end mouseUp
Tip: In this example, each property name will be written followed by the "|" character
and the property value and then a return character.
For more details, see the properties property in the LiveCode Dictionary.
to:
!!Modificare i template

Ogni novo oggetto che viene creato parte da tutta una serie di impostazione da un modello chiamato '''template'''. Alcuni programmatori sostengono che sia meglio cambiare il template e poi creare gli oggetti. La mia personale opinione e' che a meno di progetti molto grandi dove bisogna persoanlizzare tutto, il template e' meglio lasciarlo cosi' come e'.

Comunqe se siete interessati a cambiare il template, basta aggiungere la prefisso  '''template''' all'oggetto della proprieta' che intendete modificare per modificarne il template. Ad esempio
 set the text of templateField to "prova testo"

Per fortuna se fate pasticci la parola '''reset''' vi viene in aiuto, ripristinando il template allo stato originario:

 reset the templateField


!!Salvare le proprieta'

Puo' essee comodo salvare tutte le proprieta di un oggetto (comprese le custom) in un singolo array (matrice), per farlo basta scrivere:

 put the properties of  field "esempio" into backupProprieta

Come vedete con la parola '''properties''' prendete tutte le proprieta' in una volta sola. E potete anche impostare tutte le proprieta' di un oggetto in questa maniera.

!!Profili delle proprieta'
January 23, 2014, at 11:56 AM by Massimiliano Vessi -
Changed line 1273 from:
 delete word 2 of esempio @ adesso e' "Ciao tutt"
to:
 delete word 2 of esempio # adesso e' "Ciao tutt"
January 23, 2014, at 11:55 AM by Massimiliano Vessi -
Added lines 1266-1274:

!!Cancellare del testo

Usate ala parola '''delete'' per cancellare una parte del testo, ad esempio:

 put "Ciao a tutti" into esempio
 delete last char of esempio  # adesso e' "Ciao a tutt"
 delete word 2 of esempio @ adesso e' "Ciao tutt"

January 23, 2014, at 11:51 AM by Massimiliano Vessi -
Changed lines 1428-1482 from:
 

The imageSource, linkText, and visited properties

The imageSource of a character specifies an image to be substituted for that character
when the field is displayed. You use the imageSource to display images inside fields:

set the imageSource of char 17 of field 1 to 49232set the imageSource of char thisChar of field \

"My Field" to "http://www.example.com/banner.jpg"

The linkText property of a chunk lets you associate hidden text with part of a field'stext. You can use the linkText in a linkClicked handler to specify the destination
of a hyperlink, or for any other purpose.

The visited property specifies whether you have clicked on a text group during thecurrent session. You can get the visited property for any chunk in a field, but it ismeaningless unless the chunk's textStyle includes "link".

The imageSource, linkText, and visited properties are the only properties thatcan be set to a chunk of a field, but not to the entire field or any other object. Becausethey are applied to text in fields, they are listed as field properties in the LiveCodeDictionary.

7.5 Creating and Deleting Objects
LiveCode allows you to create and delete objects programmatically. You may optionally
specify all the properties for a new object before creating it.

 
7.5.1 The Create Object Command
You use the create command to create a new object.

create [invisible] type [name] [in group]

The type is any control that can be on a card: field, button, image, scrollbar, graphic,
player, or EPS.

The name is the name of the newly created object. If you don't specify a name, the object
is created with a default name.

The group is any group that's on the current card. If you specify a group, the new objectis a member of the group, and exists on each card that has the group. If you don't specify
a group, the object is created on the current card and appears only on that card.

create button "Click Me"
create invisible field in first group

For more details, see the create command in the LiveCode Dictionary. For details on how
to specify the properties of an object before creating it, see the section on Creating
Objects Off-screen Using Template Objects, below.

7.5.2 The Delete Object Command
You can use the delete command to remove objects from the stack.

delete {object}

The object is any available object.

delete this card
delete button "New Button"

For more details, see the delete command in the LiveCode Dictionary.
to:
!!Creare o cancellare oggetti

Potete creare oggetti con la parola '''create''', ad esempio:

 create button "Esempio"

potete anche specificare dove usando la parola '''in'''.

Potete cancellare un oggetto con la parola '''delete''':

 delete button "Esempio"

'''delete''' puo' essere usato anche per cancellare lettere, parole, item, ecc., dai testi.



7.5.3 Creating Objects Off-screen Using Template Objects
LiveCode uses template objects to allow you to specify the properties for an object beforeit is created. The template objects are off-screen models – there is one for each possibletype of object, e.g. button, field, graphic, etc.

If you need to create a new object and then set some properties on the object, it is moreefficient to make the changes to the template object, then create the object. Because theobject can be created with all of its properties set correctly, there is no need to lock thescreen and update or reposition the object after creating it. For example, the LiveCodedevelopment environment uses the template objects internally to create new objects fromthe main tool palette.

January 23, 2014, at 11:32 AM by Massimiliano Vessi -
Changed lines 1400-1417 from:

7.2 Properties
A property is an attribute of a LiveCode object. Each type of object has many built-in
properties, which affect the object
's appearance or behavior. You can also define customproperties for any object, and use them to store any kind of data.

This topic discusses how to use properties, how properties are inherited between objects,

and how to create and switch between collections of property settings.

To fully understand this topic, you should know how to create objects, how to use an

object's property inspector, and how to write short scripts.

7.2.1 Using Object Properties
A property is an attribute of an object
, and each object type has its own set of built-in
properties appropriate for that type. An object can be completely described by its built-in
properties; if you could make all the properties of two objects identical, they'd be thesame object. It is thus possible to describe an object entirely as an array of properties
, or
to export and import properties using text or XML files. More details on some of themethods you can use to do this are covered later in this chapter.

Note
: Since no two objects can have the same ID property, it's not possible in practicefor two different objects to become the same object, because the ID will always bedifferent.
to:
!!Proprieta'

Come gia' accennato e' possibile accedere alle proprieta' piu' importanti dalla finestra ''Property Inspector'', comunque ce ne sono molte di piu
' per ogni oggetto. Ogni proprieta' puo' essere letta o impostata anche con un comando. Per leggere basta scrivere:
 put the text of field "esempio" into miaVariabile

Per impostare una proprieta' basta usare il comando '''set''':
 set the text of field "esempio" to "Ciao a tutti"

Se impostate una proprieta' che prima non esisteva, creerete una ''Custom property'' che ritroverete nella lista delle
''custom property'' nel ''Property Inspector''.

Alcune (rare) proprieta' molto critiche possono essere solo lette.

Le proprieta' possono contenere qualsiasi cosa: testi
, numeri, dati, immaggini, file binari, array, qualsiasi cosa.

Certe proprieta' sono vuote (''empty'') nel senso che non si discostano dal comportamento standard. Ad esempio se creo un testo, la proprieta' '''testFont''' è vuota, nel senso che usa il font standard di Livecode (qualunque esso sia sul computer in uso, sulla versione di Livecode in uso)
, ma se per la mia applicazione ho la necessita' di sapere esattamente il font utilizzato, devo usare la parola '''effective'''. La parola '''effective''' ricerca esattamente il valore della proprieta', quidi:
 put the textFont of label "testo" into esempio  # cosi'  esempio non contiene nulla
 put the effective textFont of label "testo"  into esempio # cosi' esempio contiene "Helvetica"

Questo vale per tutte le proprieta'.

!!Proprieta' del testo
Al contrario di tutte le altre proprieta' il testo e' piu' versatile. E' possibile impostare le proprieta' dei testi, come ad esempio il font o la grandezza, sia a tutto il testo, sia separatamente ad ogni singolo caratte, parola, item o linea. Quindi tutti i seguenti comandi sono validi:
 set the textFont of word 3 of field "My Field" to "Courier"
 set the foregroundColor of line 1 of field 2 to "green"
 if the textStyle of the clickChunk is "bold" then beep

chiaramente di un testo con diversi stili, grandezze dei font, ecc., chiedendo la proprieta' complessiva, otterremo come risposta: "mixed".

Deleted lines 1428-1640:
Built-in properties determine the appearance and behavior of stacks and their contents-fonts,
colors, window types, size and placement, and much more – as well as much of thebehavior of the LiveCode application. By changing properties, you can change almostany aspect of your application. When you combine the ability to change properties with
the ability to create and delete objects programmatically, you can modify every aspect ofyour application (subject to any limitations of the license agreement applicable to your
edition of LiveCode).

7.2.2 Referring to properties
Property references consist of the word the, the property name, the word of, and a
reference to the object:

the armedIcon of button "My Button"
the borderWidth of field ID 2394
the name of card 1 of stack "My Stack"

Properties are sources of value, so you can get the value of a property by using it in an
expression:

put the height of field "Text" into myVarput the width of image "My Image" + 17 after field "Values"
if item 1 of the location of me > zero then beep

For example, to use the width property of a button as part of an arithmetic expression,
use a statement like the following:

add the width of button "Cancel" to totalWidths

The value of the property – in this case, the width of the button in pixels – is substituted
for the property reference when the statement is executed.
Tip: To see a list of all the language words (including properties) applicable to a
particular object type, open the Documentation window, click Dictionary, right-click on
the header bar to turn on the object type you want, then sort the list by clicking on thatobject header.
7.2.3 Changing properties
To change the value of a property, you use the set command:

set the borderColor of group "My Group" to "red"
set the top of image ID 3461 to zero

You can also see and change many of an object's properties by selecting the object and
choosing Object Inspector. See the chapter Building a User Interface for more details.

 
Most built-in properties affect the appearance or behavior of the object. For example, abutton's height, width, and location are properties of the button. Changing theseproperties in a handler causes the button's appearance to change. Conversely, dragging or
resizing the button changes the related properties.

Read-only properties

Some properties can be read, but not set. These are called read-only properties. Trying to
set a read-only property causes an execution error.

To find out whether a property is read-only, check its entry in the LiveCode Dictionary.

Changing a part of a property

Properties are not containers, so you cannot use a chunk expression to change a part of
the property. However, you can use a chunk expression to examine part of a property. For
example, you cannot set line 1 of a property to a new value: you must set the wholeproperty. For more details see the section Chunk Expressions in the chapter on
Processing Text and Data.

To change one part of a property, first put the property value into a variable, change therequired part of the variable, then set the property back to the new variable contents:

put the rect of me into tempRectput "10" into item 2 of tempRectset the rect of me to tempRect

Custom properties and virtual properties

A custom property is a property that you define. You can create as many customproperties for an object as you want, and put any kind of data into them, including binary
data or array data. You can even store a file in a custom property.

Virtual properties are custom properties that trigger a custom script action when you
change them, allowing you to implement "virtual" object behaviors.

Custom properties and virtual properties are covered in their respective sections later in
this chapter.

7.2.4 Property Inheritance
Most properties are specific to the object they are part of, and affect only that object.

However, some properties of an object, such as its color and text font, take on the settingsof the object above it in the object hierarchy. For example, if a field's background color
property is not specified (that is, if its backgroundColor property is empty), the field
takes on the background color of the card that owns it. If no background color is specified
for the card either, the stack's background color is used, and so on. This means you can
set a background color for a stack, and every object in it will automatically use thatbackground color, without your having to set it for each object.

 
This process of first checking the object, then the object's owner, then the object that
owns that object, and so on, is called inheritance of properties. Each object inherits thebackground color of the object above it in the hierarchy. Similar inheritance rules apply
to the foregroundColor, topColor, bottomColor, borderColor,
shadowColor, and focusColor properties, to their corresponding pattern properties,
and to the textFont, textSize, and textStyle properties.

7.2.5 Overriding inheritance
Inheritance is used to determine an object's appearance only if the object itself has no
setting for the property. If an inheritable property of an object is not empty, that setting
overrides any setting the object might inherit from an object above it in the objecthierarchy.

For example, if a button's backgroundColor property is set to a color referenceinstead of being empty, the button uses that background color, regardless of the button'sowners. If the object has a color of its own, that color is always used.

The effective keyword

If an inheritable property of an object is empty, you can't simply check the property to
find out what color or font settings the object displays. In this case, use the effective
keyword to obtain the inherited setting of the property. The effective keyword
searches the object's owners, if necessary, to find out what setting is actually used.

For example, suppose you have a field whose textFont property is empty. The
textFont of the card that the field is on is set to "Helvetica", so the field inherits thissetting and displays its text in the Helvetica font. To find out what font the field is using,
use the expression the effective textFont:

get the textFont of field "My Field" -- emptyget the effective textFont of field "My Field" -- Helvetica

You can use the effective keyword with any inherited property.

7.3 Global Properties
LiveCode also has global properties, which affect the overall behavior of the application.
Global properties are accessed and changed the same way as object properties. They do
not belong to any particular object, but otherwise they behave like object properties.

Tip: To see a list of all global properties, open the Message Box, and choose the Global
Properties icon – the third icon from the left at the top of the window. To see a list of all
properties in the language, including both global and object properties, use thepropertyNames global property.
 
A few properties are both global and object properties. For example, the
paintCompression is a global property, and also a property of images. For theseproperties, the global setting is separate from the setting for an individual object.

Some other global properties are affected by system settings. For example, the default
value of the playLoudness property is set by the operating system's sound volume
setting.

7.3.1 Referring to global properties
You refer to global properties using the and the property name:

the defaultFolder
the emacsKeyBindingsthe fileType

Since global properties apply to the whole application, you don't include an objectreference when referring to them.

Global properties are sources of value, so you can get the value of a global property by
using it in an expression:

get the stacksInUseput the recentNames into field "Recent Cards"
if the ftpProxy is empty then exit setMyProxy

7.3.2 Changing global properties
To change a global property, you use the set command, in the same way as for object
properties:

set the itemDelimiter to "/"
set the grid to falseset the idleTicks to 10

Some global properties can be changed by other commands. For example, thelockScreen property can either be set directly, or changed using the lock screen
and unlock screen commands. The following two statements are equivalent:

set the lockScreen to false -- does the same thing as...
unlock screen

7.3.3 Saving and restoring global properties
Object properties are part of an object, so they are saved when the stack containing their
object is saved. Global properties, however, are not associated with any object, so they
are not saved with a stack. If you change the value of a global property, the change is lostwhen you quit the application.

 
If you want to use the same setting of a global property during a different session of your
application, you must save the setting – in a Preferences file, in a custom property, or
elsewhere in a saved file – and restore it when your application starts up.

7.4 Text Related Properties
Normally, properties are applied only to objects or, in the case of global properties, to theentire application. However, a few properties also apply to chunks in a field or to singlecharacters in a field.

7.4.1 Text style properties
Certain text-related properties can be applied either to an entire field or to a chunk of afield:

set the textFont of word 3 of field "My Field" to "Courier"
set the foregroundColor of line 1 of field 2 to "green"
if the textStyle of the clickChunk is "bold" then beep

The following field properties can be applied to either an entire field or to a chunk of thefield:

textFont, textStyle, and textSize
textShift
backgroundColor and foregroundColorbackgroundPattern and foregroundPattern (Unix systems)

Each chunk of a field inherits these properties from the field, in the same way that fieldsinherit from their owners. For example, if a word's textFont property is empty, the
word is displayed in the field's font. But if you set the word's textFont to another font
name, that word – and only that word – is displayed in its own font.

To find the text style of a chunk in a field, whether that chunk uses its own styles or
inherits them from the field, use the effective keyword:

get the effective textFont of word 3 of field ID 2355answer the effective backgroundColor of char 2 to 7 \

of field "My Field"

Tip: If a chunk expression includes more than one style, the corresponding property for
that chunk reports "mixed". For example, if the first line of a field has a textSize of "12",
and the second line has a textSize of "24", an expression like the textSize of line 1 to 2 of
field "My Field" reports "mixed".
 
7.4.2 Formatted text properties
The htmlText, RTFText, and unicodeText properties of a chunk are equal to thetext of that chunk, along with the formatting information that's appropriate for the
property.

For example, if a field contains the text "This is a test.", and the word "is" is boldfaced,
the htmlText of word 2 reports "<b>is</b>".

For more information on these properties see the chapter on Processing Text and Data, as
well as the individual entries for these properties in the LiveCode Dictionary.

The formattedRect and related properties

The formattedRect property (along with the formattedWidth,
formattedHeight, formattedLeft, and formattedTop) reports the position
of a chunk of text in a field. These properties are read-only.

The formattedRect, formattedLeft, and formattedTop properties can be
used for a chunk of a field, but not the entire field. The formattedWidth and
formattedHeight apply to both fields and chunks of text in a field.
January 23, 2014, at 11:11 AM by Massimiliano Vessi -
Changed lines 1375-1376 from:
*''numero'' (Livecode assegna un numero progressivo ad ogni elemento, ma capire questo numero non e' molto semplice o affidabile)
to:
*''numero'' (Livecode assegna un numero progressivo ad ogni elemento, ma capire questo numero non e' molto semplice o affidabile. Potete usare anche parole che specificano un numero come '''first''' or '''last'''.)
Added lines 1385-1392:
e' possibile, ma fortemente sconsigliata, usare la parola '''control''' invece che della parola che identifica il vostro oggetto (field, button, ecc.). Io lo sconsiglio perche' risulta poi impossibile capire eventuali errori di programmazione. Comunque ecco un esempio:

 set the text of control ID 1062 to "Ciao a tutti"

Chiaramente certe volte e' meglio specificare bene a quale oggetto facciamo riferimetno, altrimenti Livecode pensara' che stiamo parlando della carta corrente dello stack corrente; esempio:

 set the text of field "CampoCognome" of card "InserimentoDati" to "Ciao a tutti"
 set the text of field "CampoCognome" of card "InserimentoDati" of stack "FinestraPrincipale" to "Ciao a tutti"
Changed lines 1395-1533 from:
7.1 Referring to Objects
In general, you can refer to any object by its name, number, or ID property.

7.1.1 Referring to objects by name
You can refer to an object using its object type followed by its name. For example, to
refer to a button named "OK", use the phrase button "OK":

set the loc of button "OK" to 32,104

To change an object's name, enter a name in the object's property inspector, or use the
set command to change the object's name property:

set the name of field "Old Name" to "New Name"
select after text of field "New Name"

7.1.2 Referring to objects by number
A control's number is its layer on the card, from back to front. A card's number is itsposition in the stack. A stack's number is the order of its creation in the stack file. A main
stack's number is always zero.

You can refer to an object using its object type followed by its number. For example, to
refer to the third-from-the-back field on a card, use the phrase field 3:

set the backgroundColor of field 3 to blue

To change the number of a card or control, change the Layer box in the Size & Position
pane of the object's property inspector, or use the set command to change the object's
layer property:

set the layer of field "Backmost" to 1

Tip: New objects are always created at the top layer. To refer to an object you've justcreated, use the ordinal last:
Tip: create button
set the name of last button to "My New Button"
7.1.3 Referring to objects by ID
Each object in LiveCode has an ID number. The ID property never changes (except for
stack IDs), and is guaranteed unique within the stack: no two objects in the same stack
can have the same ID property.

 
You can refer to an object using its object type, then keyword ID, followed by its ID
number. For example, to refer to a card whose ID property is 1154, use the phrase card
ID 1154:

go to card ID 1154

You cannot change an object's ID property (except for a stack).

Important: Wherever possible, you should name your objects and refer to them by
name instead of using number or ID. Both the number and ID properties will change ifobjects are copied and pasted. Additionally, your scripts will rapidly become difficult to
read if there are many ID or numerical references to objects.
7.1.4 Referring to objects by ordinal
You can refer to an object using its object type followed by the ordinal numbers first
through tenth, or the special ordinals middle and last. To refer to a random object,
use the special ordinal any. For example, to refer to the last card in the current stack, use
the special ordinal last:

go to last card

7.1.5 The special descriptor .this'
Use the this keyword to indicate the current stack, or the current card of a stack:

set the backgroundColor of this stack to whitesend "mouseUp" to this cardset the textFont of this card of stack "Menubar" to "Sans"

7.1.6 Control references
A control is any object that can appear on a card. Fields, buttons, scrollbars, images,
graphics, players, EPS objects, and groups are all controls. Stacks, cards, audio clips, and
video clips are not controls.

You can refer to an object of any of these object types using the word "control", followed
by an ID, name, or number:

hide control ID 2566
send mouseDown to control "My Button"
set the hilite of control 20 to false

If you use a name, as in the expression control "Thing", the reference is to the
first control (with the lowest layer) that has that name.

 
When you refer to a control by number using its object type, the reference is to the Nth
control of that type. For example, the phrase field 1 refers to the lowest field on the
card. This may not be the lowest control, because there may be controls of other typesunderneath field 1. However, when you refer to a control by number using the word
control, the reference is to the Nth control of any type. The phrase control 1
refers to the lowest control on the card, which may be of any type.

Tip: To refer to the object underneath the mouse pointer, use the mouseControl
function.
7.1.7 Nested Object References
To refer to an object that belongs to another object, nest the references in the same order
as the object hierarchy. For example, if there is a button called "My Button" on a card
called "My Card", you can refer to the button like this:

show button "My Button" of card "My Card"

You can mix names, numbers, ordinal references, and IDs in a nested object reference,
and you can nest references to whatever depth is required to specify the object. The only
requirement is that the order of references be the same as the order of the objecthierarchy, going from an object to the object that owns it. Here are some examples:

field ID 34 of card "Holder"
player 2 of group "Main" of card ID 20 of stack "Demo"
first card of this stack
stack "Dialog" of stack "Main" -- "Dialog" is a substack


If you don't specify a card in referring to an object that is contained by a card, LiveCodeassumes the object is on the current card. If you don't specify a stack, LiveCode assumesthe object is in the current stack. You can reference a control in another stack by either ofthe following methods:

Use a nested reference that includes the name of the stack:

field 1 of stack "My Stack"
graphic "Outline" of card "Tools" of stack "Some Stack"


Set the defaultStack property to the stack you want to refer to first. The
defaultStack specifies the current stack, so you can refer to any object in the
defaultStack without including a stack name. This example sets a checkbox in thecurrent stack to have the same setting as a checkbox in another stack called "Other
Stack":

put the defaultStack into savedDefault-- so you can set it back later

 
set the defaultStack to "Other Stack"
put the hilite of button "Me" into meSetting-- this button is in "Other Stack"
set the defaultStack to savedDefault
set the hilite of button "Me Too" to meSetting-- this button is in the original stack

If an object is in a group, you can include or omit a reference to the group in a nested
reference to the object. For example, suppose the current card contains a button called
"Guido", which is part of a group called "Stereotypes". You can refer to the button with
any of the following expressions:

button "Guido"
button "Guido" of card 5
button "Guido" of group "Stereotypes"
button "Guido" of group "Stereotypes" of card 5


If there is no other button named "Guido" on the card, these examples are equivalent. Ifthere is another button with the same name in another group (or on the card, but not in
any group), you must either specify the group (as in the second and third examples) or
refer to the button by its ID property, to be sure you're referring to the correct button.
to:
Altri programmatori, ma io lo socnsiglio, prefriscono impostarre la variabile '''DefaultStack''' per indicare a che stack si riferiscono, ma anche qui io credo che crei non pochi problemi, se sfugge la riga con ''defaultstack'',capire perche' un programma non funziona.

Quando un oggetto fa parte di un gruppo, potete specificarlo per evitare confusioni con eventuali omonimie:
 button "Guido" of group "Stereotipi"


7.2 Properties
A property is an attribute of a LiveCode object. Each type of object has many built-in
properties, which affect the object's appearance or behavior. You can also define customproperties for any object, and use them to store any kind of data.

This topic discusses how to use properties, how properties are inherited between objects,
and how to create and switch between collections of property settings.

To fully understand this topic, you should know how to create objects, how to use an
object's property inspector, and how to write short scripts.

7.2.1 Using Object Properties
A property is an attribute of an object, and each object type has its own set of built-in
properties appropriate for that type. An object can be completely described by its built-in
properties; if you could make all the properties of two objects identical, they'd be thesame object. It is thus possible to describe an object entirely as an array of properties, or
to export and import properties using text or XML files. More details on some of themethods you can use to do this are covered later in this chapter.

Note: Since no two objects can have the same ID property, it's not possible in practicefor two different objects to become the same object, because the ID will always bedifferent.
January 23, 2014, at 10:47 AM by Massimiliano Vessi -
Added lines 1352-1353:
L'esempio appena mostrato indica come sia possibili indicare una funzione per ordinare. In questo modo non avete limite alle possibilita' di ordinamento.
Changed lines 1357-1366 from:


sort cards by field "Last Name"

To sort cards by the numeric value in a ZIP Code:

sort cards numeric by field "ZIP code"

Tip: To sort cards by a custom expression that performs a calculation, you can create acustom function
: 
Tip: sort cards by myFunction() -- uses function below
to:
e' possibile ordinarle anche indicando un elemento della carta:

 sort cards by field "Cognome"


!Interfaccia grafica

In questo capitolo studieremo meglio gli aspetti riguardanti gli elementi grafici, come modificarli e piegarli al nostro volere con poche righe di codice
:
Changed lines 1366-1368 from:
Tip: function myFunctionput the number of buttons of this card into tValue-- perform any calculation on tValue herereturn tValue
-- sort will use this value
end myFunction
to:
!!Riferirsi agli oggetti

Ogni oggetto puo' essere indicato in diversi modi:

*'''me''' (me)
*'''this ...''' (questo ...)
*'''the target''' (l'obbiettivo del messaggio corrente)
*''nome'' (ogni oggetto  ha un nome)
*''ID'' (Livecode assegna un ID unico ad ogni elemento di una carta, ma l'ID si puo' ripetere in un'altra carta)
*''numero'' (Livecode assegna un numero progressivo ad ogni elemento, ma capire questo numero non e' molto semplice o affidabile)

vediamo praticamente:
 set the text of me to "Ciao a tutti"
 set the text of title of this stack to "Esempio"
 set the text of the target to "Ciao a tutti"
 set the text of field "CampoNome" to "Ciao a tutti"
 set the text of field ID 1062 to "Ciao a tutti"
 set the text of field 2 to "Ciao a tutti"

Changed lines 1386-1398 from:
Chapter 7 Programming a User Interface

The user interface for your application is often one of its most important features. In
Chapter 4 we looked at how you build a user interface using LiveCode’s tools and
development environment. In this chapter we look at how you can edit, or even build auser interface programmatically. Everything you can do using the built-in tools you can
also do programmatically. You can even create and modify a user interface at run time in
a standalone application, or provide interactive methods for your users to modify specificaspects of your application. This set of capabilities allow you to produce applications thatconstruct their interface using XML files or a custom data structure, programmatically
construct aspects of complex interfaces, modify their look using user specified
parameters, create themed or skinned interface options, build your own interface editing
tools that plug-in to LiveCode’s IDE and much more. You can also create custom objectsand attach your own virtual behaviors and custom properties to them. We recommend
you spend a little time becoming familiar with building an interface using the tools in thedevelopment environment before creating or editing an interface programmatically.

 
to:
Deleted lines 7517-7518:

! I vostri commenti
January 22, 2014, at 06:18 PM by Massimiliano Vessi -
Changed lines 1349-1409 from:
 put the number of lines of esempio into tElementCount
 sort lines of tExampleList ascending numeric by random(tElementCount)


6.8.3 The Sort Container Command: Sorting Randomly
To sort randomly, use the random function to generate a random number as the sortKey
for each line or item, instead of evaluating the line or item's contents. For example:

put the number of lines of tExampleList into tElementCount
sort lines of tExampleList ascending numeric by random(tElementCount)

6.8.4 The Sort Container Command: Stable Sorts – Sorting onMultiple Keys
To sort a list by multiple criteria you can sort multiple times. This is because LiveCodeuses a stable sort, meaning that if two items have the same sort key their relative order in
the output will not change. To perform a stable sort, start with the least significant or
important criteria and work up to the most important or significant. For example:

sort lines of fld 1 ascending numeric by item 2 \
of each
sort lines of fld 1 ascending text by the \
first item of each

Original list:

Result:

Oliver,1.54Elanor,5.67Elanor,5.67Elanor,6.34Marcus,8.99Marcus,8.99Elanor,6.34Oliver,1.54Oliver,8.99Oliver,8.99Tim,3.44 Tim,3.44

Figure 57 – Results of sorting multiple items

Tip: If you have a large data set and want to improve performance by only performing a
single sort, you can construct a sort key that gives the appropriate ordering. In this
example a good way to do that is to use the format function to construct a fixed length
string, one element per sort:
Tip: sort lines of fld 1 ascending text by \
format("%-16s%08.2f", item 1 of each, item 2 of each)
Tip: This formats each individual line similar to the following:
 
Tip: Oliver 00001.54
Elanor 00005.67
Tip: These lines now sort the required way as if the first field (the name) ties, the order is
determined by the second field – due to the use of padding characters making all the
fields the same size.
6.8.5 Sorting Cards
To sort cards, use the sort command.

sort [marked] cards [of stack] [direction] [sortType] bysortKey

The stack is a reference to any open stack. If you don't specify a stack, the cards of thecurrent stack are sorted.

The direction is either ascending or descending. If you don't specify a direction, the sort
is ascending.

The sortType is one of text, international, numeric, or dateTime. If you don't specify asortType, the sort is by text.

The sortKey is an expression that evaluates to a value for each card in the stack. Any
object references within the sortKey are treated as pertaining to each card being
evaluated, so for example, a reference to a field is evaluated according to that field'scontents on each card. Typically the sort command is used with background fields that
have their sharedText property set to false so that they contain a different value on each
card.

For example to sort cards by the contents of the last name field on each:
to:
 put the number of lines of esempio into numerorighe
 sort lines of esempio by random(numerorighe)

E' possibile anche mettere in ordine le carte (card) di una finestra (stack). Questa opzione è fondamentale quando volete creare delle stampe o dei PDF, ogni carta sara' una pagina, quindi e' estremamente importante che siano tutte nell'ordine giusto.
 sort cards of this stack



sort cards by field "Last Name"

To sort cards by the numeric value in a ZIP Code:

sort cards numeric by field "ZIP code"

Tip: To sort cards by a custom expression that performs a calculation, you can create acustom function:
Tip: sort cards by myFunction() -- uses function below
January 22, 2014, at 04:54 PM by Massimiliano Vessi -
Changed lines 1344-1387 from:
si possono


sort lines of field "sample text" ascending text
sort lines of tText descending text

The following example sorts a collection of items numerically:

sort items of field "sample csv" ascending numericsort items of tItems descending numeric

6.8.2 The Sort Container Command: Using Sort Keys
The sortKey syntax allows you to sort each line or item based on the results of an
evaluation performed on each line or item.

To sort the lines of a container by a specific item in each line:

sort lines of tContainer by the first item of each
sort lines of tContainer by item 3 of each

The sortKey expression will only be evaluated once for every element that is to be sorted.
This syntax allows a variety of more complex sort operations to be performed.

The following example will extract the minimum and maximum integers present in a list:

set the itemDelimiter to "."
sort lines of fld 1 numeric by char 2 to -1 of the first item of each
put char 2 to -1 of the first item of the first line of fld 1 into tMinimumInteger
put char 2 to -1 of the first item of the last line of fld 1 into tMaximumInteger

Original list:

Result:

F54.mov tMinimumInteger is 3

 
M27.mov

tMaximumInteger is 54
M7.mov
F3.mov

Figure 56 – Results of sort command using sort key

to:
si possono scrivere espressioni molto complesse:

 sort lines of fld 1 numeric by char 2 to -1 of the first item of each

E' possibile anche ordinare in sequenza casuale, ecco un esempio:
 put the number of lines of esempio into tElementCount
 sort lines of tExampleList ascending numeric by random(tElementCount)

Changed lines 1357-1360 from:
put the number of lines of tExampleList into \
tElementCount
sort
lines of tExampleList ascending numeric by \
random(tElementCount)
to:
put the number of lines of tExampleList into tElementCount
sort lines of tExampleList ascending numeric by random(tElementCount)
January 22, 2014, at 04:46 PM by Massimiliano Vessi -
Changed lines 1284-1312 from:
Ordinare dati , righe, testi e' un'operazione importante ma anche semplice utilizzando il comando '''sort'''.

6.8 Sorting
Sorting data is a common and fundamental operation. Sorting allows you to display datain a user-friendly fashion or code a number of algorithms. LiveCode's intuitive sort
features give you the power and flexibility to perform any kind of sorting you may
require.

6.8.1 The Sort Container Command: Overview
To sort data, use the sort container command.

sort [{lines | items} of] container [direction] [sortType]
[by sortKey]

The container is a field, button, or variable, or the message box.

 
The direction is either ascending or descending. If you don't specify a direction, the sort
is ascending.

The sortType is one of text, numeric, or dateTime. If you don't specify a sortType, thesort is by text.

The sortKey is an expression that evaluates to a value for each line or item in thecontainer. If the sortKey contains a chunk expression, the keyword each indicates that
the chunk expression is evaluated for each line or item. If you don't specify a sortKey, the
entire line (or item) is used as the sortKey.

The following example sorts the lines of a variable alphabetically:

sort lines of field "sample text" ascending textsort lines of tText descending text

to:
Ordinare dati , righe, testi e' un'operazione importante ma anche semplice utilizzando il comando '''sort'''.  Con sort potete operare su righe o items o entrambi, ma per semplicita' visiva cerchero' sempre di utilizzare le righe.Vediamo qualche esempio considerando il testo ''esempio'' cosi' composto:
 1
 3
 5
 4
 2

poi proviamo ad ordinarle:

 sort lines of esempio

adesso esempio contiene

 1
 2
 3
 4
 5

possiamo invertire l'ordinamento
 sort  lines of  esempio descending
cosi' esempio contiene:
 5
 4
 3
 2
 1

'''NOTA''': se si ha a che fare con i numeri, bisogna specificarlo. L'ordinamento di solito avviene secondo la modalità "testo".  Il comando '''sort''' supporta le seguenti modalita':
* text
*numeric
*dateTime

Esempi:
 sort  lines of  esempio descending
 5
 4
 3
 2
 10

 sort  lines of  esempio descending numeric
 10
 5
 4
 3
 2


L'opzione piu' interessante e' che e' possibile specificare di ordinare le righe solo secondo elementi di ogni riga, utilizzando l'opzione '''by ... of each'''. Ad esempio prendiamo un testo fatto cosi':
 10, mario, 15/5/2010
 23, luigi, 10/2/2009
 30, andrea, 27/7/2013

ora proviamo ad ordinarlo secondo i nomi:
 sort lines of esempio by item 2 of each
 30, andrea, 27/7/2013
 23, luigi, 10/2/2009
 10, mario, 15/5/2010

si possono


sort lines of field "sample text" ascending text
sort lines of tText descending text

Changed lines 1360-1361 from:
sort lines of tContainer by the first item of eachsort lines of tContainer by item 3 of each
to:
sort lines of tContainer by the first item of each
sort
lines of tContainer by item 3 of each
Changed lines 1369-1373 from:
sort lines of fld 1 numeric by char 2 to -1 of the \
first item of each
put char 2 to -1 of the first item of the first line \
of fld 1 into tMinimumIntegerput char 2 to -1 of the first item of the last line of \
fld 1 into tMaximumInteger
to:
sort lines of fld 1 numeric by char 2 to -1 of the first item of each
put char 2 to -1 of the first item of the first line of fld 1 into tMinimumInteger
put
char 2 to -1 of the first item of the last line of fld 1 into tMaximumInteger
January 22, 2014, at 03:56 PM by Massimiliano Vessi -
Changed lines 1283-1288 from:



6.7 XML
Extensible Markup Language
, or XML, is a general-purpose language for exchanging
structured data between different applications and across the Internet. It consists of text
to:
!Ordinare i dati
Ordinare dati
, righe, testi e' un'operazione importante ma anche semplice utilizzando il comando '''sort'''.

6.8 Sorting
Sorting data is a common and fundamental operation. Sorting allows you to display datain a user-friendly fashion or code a number of algorithms. LiveCode's intuitive sort
features give you the power and flexibility to perform any kind of sorting you may
require.

6.8.1 The Sort Container Command: Overview
To sort data, use the sort container command.

sort [{lines | items} of] container [direction] [sortType]
[by sortKey]

The container is a field, button, or variable, or the message box.

Changed lines 1300-1325 from:
documents organized into a tree structure. It can generally be understood by both human
and machine
.

LiveCode includes comprehensive support for XML through its built-in XML library.
Additionally, standards exist to support exchange of XML over a network connection (or
"web services") – most notably through the XML-RPC and SOAP protocols. LiveCodeincludes a library for using XML-RPC and there are examples of using LiveCode to build
SOAP applications available.

6.7.1 The XML Tree Structure
XML is simply
a data tree. It must start with a root node, be well formed and nested.
Tags may not overlap. For more information on XML see

http://en.wikipedia.org/wiki/XML

Figure 52 below shows a typical XML tree. In this example we have represented
a simplestack file as XML. The stack file has a single stack with two cards. On the first card thereis a field named "Hello" with the contents "Hello World!". There is a second card, which
is blank.


Figure 55 – XML Tree Representation of a Stack

Root node Root element, The start of
the XML document, which
document element includes
a declaration the file is XML, theversion of XML in use and the text encoding
Comment Comments can be placed anywhere in thetree. They start with <! and end with ->. They
must not contain double dashes --
Node Element, tag The items that makes up the content within

to:
The direction is either ascending or descending. If you don't specify a direction, the sort
is ascending
.

The sortType is one of text, numeric, or dateTime. If you don't specify a sortType, thesort is by text.

The sortKey is an expression that evaluates to a value for each line or item in thecontainer. If the sortKey contains a chunk expression, the keyword each indicates that
the chunk expression is evaluated for each line or item. If you don't specify
a sortKey, the
entire line (or item) is used as the sortKey.

The following example sorts the lines of a variable alphabetically:

sort lines of field "sample text" ascending textsort lines of tText descending text

The following example sorts
a collection of items numerically:

sort items of field "sample csv" ascending numericsort items of tItems descending numeric

6.8.2 The Sort Container Command: Using Sort Keys
The sortKey syntax allows you to sort each line or item based on the results of an
evaluation performed on each line or item.

To sort
the lines of a container by a specific item in each line:

sort lines
of tContainer by the first item of eachsort lines of tContainer by item 3 of each

The sortKey expression will only be evaluated once for every element that is to be sorted.
This syntax allows a variety of more complex sort operations to be performed.

The following example will extract the minimum and maximum integers present in a list:

set the itemDelimiter to "."
sort lines of fld 1 numeric by char 2 to -1 of the \
first item of each
put char 2 to -1 of the first item of the first line \
of fld 1 into tMinimumIntegerput char 2 to -1 of the first item of the last line of \
fld 1 into tMaximumInteger

Original list:

Result:

F54.mov tMinimumInteger is 3

Changed lines 1344-1378 from:
an XML document

Attributes Properties attributable to a given node. Anode may have zero or more properties
Empty node Empty element A method of specifying that a node exists butis empty
Entity reference A method of specifying special characters.
XML includes support for &, <, >, ‘ and ".
Additional entities can be defined using aDocument Type Definition or DTD.


6.7.2 When to use XML
XML has a number of advantages and disadvantages. It is predominantly useful when
exchanging data between different applications or systems. However like any method ofdata storage or transfer it
is not suitable for all types of application.

The advantages of XML are: it is text based making it more easily readable by humans aswell as just machines; it is self describing; it is based on international standards
and in
widespread use with a large number of editors available for it; the hierarchical structuremakes it suitable for representing many types of document; and it is platformindependent.

The disadvantages are that: it is sometimes less efficient than binary or even other formsof text representations
of data; for simple applications it is more complicated than may
strictly be necessary; and the hierarchical model may not be suitable for all data types.

You may decide
that using XML is the best solution for your particular data storage or
transmission requirements. Or you may be working on
a project with others where using
XML or a web service based on it is a requirement. However in many cases a binary

format or database will be more appropriate. You should give consideration to themethod you intend to use as early as possible in the design of your application.

6.7.3 Methods for Handling XML in LiveCode
LiveCode includes a comprehensive XML library for working with XML documents.
Using the XML library has the advantage that we include syntax and functions for
performing the common operations on XML that you may need. However thedisadvantage is that at present the library is implemented as an external command
(included built-in to the LiveCode distribution) and thus does not benefit from nativeLiveCode-engine syntax. If you have simple XML processing requirements you may
prefer to use LiveCode’s built in chunk expression support to do the parsing, matching or
construction of XML. For more information see the section on Using Chunk Expressions.
However if you are working with complex XML then the library includes acomprehensive suite of features.

In addition to the XML library, LiveCode has a built-in script-based library for working
with XML-RPC.

to:
M27.mov

tMaximumInteger is 54
M7.mov
F3.mov

Figure 56 – Results of sort command using sort key

6.8.3 The Sort Container Command: Sorting Randomly
To sort randomly, use the random function to generate a random number as the sortKey
for each line or item, instead of evaluating the line or item's contents. For example:

put the number of lines of tExampleList into \
tElementCount
sort lines of tExampleList ascending numeric by \
random(tElementCount)

6.8.4 The Sort Container Command: Stable Sorts – Sorting onMultiple Keys
To sort a list by multiple criteria you can sort multiple times. This
is because LiveCodeuses a stable sort, meaning that if two items have the same sort key their relative order in
the output will not change. To perform a stable sort, start with the least significant or
important criteria
and work up to the most important or significant. For example:

sort lines of fld 1 ascending numeric by item 2 \
of each
sort lines of fld 1 ascending text by the \
first item of each

Original list:

Result:

Oliver,1.54Elanor,5.67Elanor,5.67Elanor,6.34Marcus,8.99Marcus,8.99Elanor,6.34Oliver,1.54Oliver,8.99Oliver,8.99Tim,3.44 Tim,3.44

Figure 57 – Results
of sorting multiple items

Tip: If you have a large data set and want to improve performance by only performing a
single sort, you can construct a sort key
that gives the appropriate ordering. In this
example a good way to do that is to use the format function to construct
a fixed length
string, one element per sort:
Tip: sort lines of fld 1 ascending text by \

format("%-16s%08.2f", item 1 of each, item 2 of each)
Tip: This formats each individual line similar
to the following:
Changed lines 1387-1420 from:
Tip: To see a list of commands for working with XML-RPC, filter the LiveCode
Dictionary with
the term XMLRPC.
Tip: An interactive stack demonstrating using the LiveCode XML library is available
from http://support.runrev.com/resources/xml.php
6.7.4 The XML Library: Loading, Displaying and Unloading XML
This section discusses using the XML library in detail.

Getting Started – Creating an XML Tree in Memory

In order to work with an XML document, you start by creating an XML tree of thatdocument in memory. There are two functions revCreateXMLTreeFromFile and
revCreateXMLTree
. Use the former to load XML document from a file and create a
tree in memory, use the latter to create an XML tree from another data source such as avariable, field or download.

revCreateXMLTree(XMLText, dontParseBadData, createTree, \
sendMessages)


revCreateXMLTreeFromFile(filePath, dontParseBadData, \
createTree, sendMessages)

In revCreateXMLTree the XMLTextis the string containing the XML. In
revCreateXMLTreeFromFile this parameter is replaced with
the filePath – the file
path
to the XML document. Both functions return a single value – the ID of the tree thathas been created.

Important: Both functions require you to specify all the parameters. You must store the
ID returned by these functions in order to access the XML tree later in your script.
The dontParseBadData specifies whether or not to attempt to parse poorly formed XML.
If this is set to true then bad data will be rejected and generate an error instead ofconstructing the tree in memory.

The createTree specifies whether to create a tree in memory or not. You will generally
want this to be true, unless you are intending only to read in an XML file to determinewhether or not it is properly structured.

The sendMessages specifies whether or not messages should be sent when parsing theXML document. Messages can be useful if you want to implement functionality such as aprogress bar, progressively render or progressively process data from a large XML file asit is being parsed. If you set this to true, revXMLStartTree will be sent when the
parsing starts, revStartXMLNode will be sent when a new node is encountered,

to:
Tip: Oliver 00001.54
Elanor 00005.67
Tip: These lines now sort the required way as if
the first field (the name) ties, the order is
determined by the second field – due to the use of padding characters making all the
fields the same size.
6.8.5 Sorting Cards
To sort cards, use the sort command.

sort [marked] cards [of stack] [direction] [sortType] bysortKey

The stack is a reference to any open stack. If you don't specify a stack, the cards of thecurrent stack are sorted
.

The direction is either ascending or descending. If you don't specify
a direction, the sort
is ascending.

The sortType is one of text, international, numeric, or dateTime. If you don't specify asortType, the sort is by text.


The sortKey is an expression that evaluates to a value for each card in the stack. Any
object references within
the sortKey are treated as pertaining to each card being
evaluated, so for example,
a reference to a field is evaluated according to that field'scontents on each card. Typically the sort command is used with background fields that
have their sharedText property set to false so that they contain a different value on each
card.

For example to sort cards by the contents of the last name field on each:

sort cards by field "Last Name"

To sort cards by the numeric value in a ZIP Code:

sort cards numeric by field "ZIP code"

Tip: To sort cards by a custom expression that performs a calculation, you can create acustom function:
Tip: sort cards by myFunction() -- uses function below
Changed lines 1421-1460 from:
revEndXMLNode will be sent when a node has been completed, revStartXMLData
will be sent at the start of a new block of data and finally revXMLEndTree will be sent
when processing is finished.

Retrieving information from an XML tree

Now that you have created your XML tree in memory (above) and stored the tree ID you
can use the functions in this section to retrieve information from within the tree.

Important: Any text you fetch using the LiveCode XML library will be in the encodingspecified in the root node of the XML tree.
Note: All the examples in this section assume that we have loaded the XML tree
depicted in Figure 52 – XML Tree Representation of a Stack, above. We assume that
you have loaded this tree using the revCreateXMLTree function described above,
and that this function has returned a value of 1 as the ID of the tree.
Retrieving the Root Node

To retrieve the root node from your XML tree, use the revXMLRootNode function.
revXMLRootNode(treeID)

The treeID contains the ID of the XML tree you want to access. For example, using thefollowing function with sample tree depicted above:

put revXMLRootNode(1) into tRootNode

Results in tVar containing: stackFile

Retrieving the First Child Element in a Node

To retrieve the first child element use revXMLFirstChild.
revXMLFirstChild(treeID,parentNode)

The parentNode contains the path to the node we want to retrieve the first child from.
Nodes are referenced using a file-path like format with / used to denote the root and
delimit nodes.

We can use this function on our sample XML as follows:

-- pass the stackFile result in retrieved in tRootNode
-- to the revXMLFirstChild function:
put revXMLFirstChild(1,tRootNode) into tFirstChild

to:
Tip: function myFunctionput the number of buttons of this card into tValue-- perform any calculation on tValue herereturn tValue
-- sort will use this value
end myFunction
Changed lines 1425-1472 from:
-- EQUIVALENT to the following:
put revXMLFirstChild(1,"stackFile") into tFirstChild

This results in tFirstChild containing: /stackFile/stack

Retrieving a list of Children in a Node

To retrieve a list of children of a node use revXMLChildNames.

revXMLChildNames(treeID, startNode, nameDelim, childName, \
includeChildCount)

The nameDelim is the delimiter that separates each name that is returned. To get a list ofnames, specify return.

The childName is the name of the type of children to list.
includeChildCount allows you to include the number of each child in square brackets
next to the name.

We can use this function on our sample XML as follows:

put revXMLChildNames(1,"/stackFile/stack", return, "card",
true) into tNamesList

This results in tNamesList containing:
card[1]
card[2]


Retrieving the Contents of the Children in a Node

To retrieve a list of children of a node including their contents, userevXMLChildContents.

revXMLChildContents(treeID,startNode,tagDelim,nodeDelim, \
includeChildCount,depth)

See above for an explanation of treeID, startNode and tagDelim.

The nodeDelim indicates the delimiter that separates the contents of the node from its
name.
The depth specifies the number of generations of children to include. If you use –1 as the


depth then all children are return.
Using this function on our example XML file as follows:


put revXMLChildContents(1, "/stackFile/stack", space, \

to:
Chapter 7 Programming a User Interface

The user interface for your application is often one of its most important features. In
Chapter 4 we looked at how you build a user interface using LiveCode’s tools and
development environment. In this chapter we look at how you can edit, or even build auser interface programmatically. Everything you can do using the built-in tools you can
also do programmatically. You can even create and modify a user interface at run time in
a standalone application, or provide interactive methods for your users to modify specificaspects of your application. This set of capabilities allow you to produce applications thatconstruct their interface using XML files or a custom data structure, programmatically
construct aspects of complex interfaces, modify their look using user specified
parameters, create themed or skinned interface options, build your own interface editing
tools that plug-in to LiveCode’s IDE and much more. You can also create custom objectsand attach your own virtual behaviors and custom properties to them. We recommend
you spend a little time becoming familiar with building an interface using the tools in thedevelopment environment before creating or editing an interface programmatically.

Changed lines 1438-1483 from:
 return, true, -1) into tContents

This results in tContents containing:

card[1]
field[1]
text[1] Hello World!
htmlText[1] <p>Hello World</p>
card[2]


Retrieving the Number of Children in a Node

To retrieve the number of children of a node revXMLNumberOfChildren.
revXMLNumberOfChildren(treeID,startNode,childName,depth)

See above for an explanation of treeID, startNode, childName and depth.

Using this function on our example XML file as follows:

put revXMLNumberOfChildren(1,
"/stackFile/stack", "card", \
-1)into tContents

This results in tContents containing: 2

Retrieving
the Parent of a Node

To retrieve a node’s parent use
the revXMLParent function.
revXMLParent(treeID,childNode)


See above for an explanation of treeID and startNode.
Using this function on our example XML file as follows:

put revXMLParent(1,"stackFile/stack") into tParent

Results in tParent containing: /stackFile

Retrieving an Attributes
from a Node

To retrieve an attribute from a node use revXMLAttribute.
revXMLAttribute(treeID,node,attributeName)

See above for an explanation
of treeID and node.
The attributeName is the name of the attribute you want to retrieve the value for.
Using this function on our example XML file as follows:


to:
7.1 Referring to Objects
In general, you can refer to any object by its name, number, or ID property.

7.1.1 Referring to objects by name
You can refer to an object using its object type followed by its name. For example, to
refer to a button named "OK", use the phrase button "OK":

set the loc of button
"OK" to 32,104

To change an object's name, enter a name in
the object's property inspector, or use the
set command to change
the object's name property:

set the name of field "Old Name" to "New Name"
select after text of field "New Name"

7.1.2 Referring to objects by number
A control's number is its layer on the card,
from back to front. A card's number is itsposition in the stack. A stack's number is the order of its creation in the stack file. A main
stack's number is always zero.

You can refer to an object using its object type followed by its number. For example, to
refer to the third-from-the-back field on a card, use the phrase field 3:

set the backgroundColor of field 3 to blue

To change the number of a card or control, change the Layer box in the Size & Position
pane of the object's property inspector, or use the set command to change the object's
layer property:

set the layer of field "Backmost" to 1

Tip: New objects are always created at the top layer. To refer to an object you've justcreated, use the ordinal last:
Tip: create button
set the name of last button to "My New Button"
7.1.3 Referring to objects by ID
Each object in LiveCode has an ID number. The ID property never changes (except for
stack IDs), and is guaranteed unique within the stack: no two objects in the same stack
can have the same ID property.

Changed lines 1477-1520 from:
put revXMLAttribute(1,"/stackFile/stack","rect") into tRect

This results in tRect containing: 117
,109,517,509

Retrieving all Attributes from
a Node

To retrieve all attributes from a node
use revXMLAttributes.
revXMLAttributes(treeID,node,valueDelim,attributeDelim)

See above for an explanation of treeID and node.
The valueDelim is delimiter that separates the attribute’s name from its value.
The attributeDelim is delimiter that separates the attribute’s name & value pair from


each other.
Using this function on our example XML file as follows:


put revXMLAttributes(1, "/stackFile/stack/card/field", \
tab, return) into tFieldAttributes

This results in tFieldAttributes containing:
name Hello

rect 100,100,200,125

Retrieving the Contents of Attributes

To retrieve the contents of a specified attribute from a node and its children, userevXMLAttributeValues.

revXMLAttributeValues(treeID, startNode, childName, \
attributeName, delimiter, depth)

See above for an explanation of treeID
, startNode and depth.

The childName is the name of the type of child to be searched. Leave this blank
to
include all types of children.
The attributeName is the name of
the attribute to return the values for.
The delimiter is the delimiter to be used to separate the values returned.
Using this function on our example XML file as follows
:


put revXMLAttributeValues(1, "/stackFile/", , "rect", \
return, -1) into tRectsList

to:
You can refer to an object using its object type, then keyword ID, followed by its ID
number. For example
, to refer to a card whose ID property is 1154, use the phrase card
ID 1154:

go to card ID 1154

You cannot change an object's ID property (except for a stack).

Important: Wherever possible, you should name your objects and refer to them by
name instead of using number or ID. Both the number and ID properties will change ifobjects are copied and pasted. Additionally, your scripts will rapidly become difficult to

read if there are many ID or numerical references to objects.
7.1.4 Referring to objects by ordinal
You can refer to an object using its object type followed by the ordinal numbers first
through tenth
, or the special ordinals middle and last. To refer to a random object,
use the special ordinal any. For example,
to refer to the last card in the current stack, use
the special ordinal last:

go to last card

7.1.5 The special descriptor .this'
Use the this keyword to indicate the current stack, or the current card of a stack
:

set the backgroundColor of this stack to whitesend "mouseUp" to this cardset the textFont of this card of stack "Menubar" to "Sans"

7.1.6 Control references
A control is any object that can appear on a card. Fields, buttons, scrollbars, images,
graphics, players, EPS objects, and groups are all controls. Stacks, cards, audio clips, and
video clips are not controls.

You can refer to an object of any of these object types using the word "control", followed
by an ID, name, or number:

hide control ID 2566
send mouseDown to control "My Button"
set the hilite of control 20 to false

If you use a name, as in the expression control "Thing", the reference is to the
first control (with the lowest layer) that has that name.

Changed lines 1517-1561 from:
This results in tRectsList containing:
117,109,517,509

100,100,200,125

Retrieving the Contents of a Node

To retrieve the contents of a specified node, use revXMLNodeContents
.
revXMLNodeContents(treeID, node)
See above for an explanation of treeID and node.
Using this function on our example XML file as follows:


put revXMLNodeContents(1, \
"/stackFile/stack/card/field/htmlText") into \
tFieldContents

This results in tFieldContents containing:
<p>Hello World</p>

Note: The entity references for
the < and > symbols have been translated into text in
this result
.
Retrieving Siblings

To retrieve the contents of
the siblings of a node, use revXMLNextSibling and
revXMLPreviousSibling.

revXMLNextSibling(treeID,siblingNode)
revXMLPreviousSibling(treeID,siblingNode)

The siblingNode is the path
to the node to retrieve the siblings from.

Using this function on our example XML file as follows:

put revXMLPreviousSibling(1, "/stackFile/stack/card[2]")\
into tPrev
put revXMLNextSibling(1, "/stackFile/stack/card") \
into tNext

This results
in tPrev containing:
/stackFile/stack/card[1]

And tNext containing:
/stackFile/stack/card[2]

to:
When you refer to a control by number using its object type, the reference is to the Nth
control of that type
. For example, the phrase field 1 refers to the lowest field on the
card. This may not be the lowest control, because there may be controls of other typesunderneath field 1. However, when you refer to a control by number using
the word
control, the reference is to the Nth control of any type
. The phrase control 1
refers to
the lowest control on the card, which may be of any type.

Tip: To refer
to the object underneath the mouse pointer, use the mouseControl
function.
7.1.7 Nested Object References
To refer to an object that belongs to another object, nest the references
in the same order
as the object hierarchy. For example, if there is a button called "My Button" on a card
called "My Card", you can refer to the button like this:

show button "My Button" of card "My Card"

You can mix names, numbers, ordinal references, and IDs in a nested object reference,
and you can nest references to whatever depth is required to specify the object. The only
requirement is that the order of references be the same as the order of the objecthierarchy, going from an object to the object that owns it. Here are some examples:

field ID 34 of card "Holder"
player 2 of group "Main" of card ID 20 of stack "Demo"
first card of this stack
stack "Dialog" of stack "Main" -- "Dialog" is a substack


If you don't specify a card in referring to an object that is contained by a card, LiveCodeassumes the object is on the current card. If you don't specify a stack, LiveCode assumesthe object is in the current stack. You can reference a control in another stack by either ofthe following methods:

Use a nested reference that includes the name of the stack:

field 1 of stack "My Stack"
graphic "Outline" of card "Tools" of stack "Some Stack"


Set the defaultStack property to the stack you want to refer to first. The
defaultStack specifies the current stack, so you can refer to any object in the
defaultStack without including a stack name. This example sets a checkbox in thecurrent stack to have the same setting as a checkbox in another stack called "Other
Stack":

put the defaultStack into savedDefault-- so you can set it back later

Changed lines 1558-1603 from:
Searching for a Node

To search for a node based on an attribute, use revXMLMatchingNode.

revXMLMatchingNode(treeID, startNode, childName, \ attributeName, attributeValue,

depth, [caseSensitive])
See above for an explanation
of treeID, startNode and depth.
The childName
is the name of the children you want to include in the search. If you leave


this blank all children are searched.
The attributeName is the name of
the attribute you want to search.
attcributeValue is the search term you want to match.
caseSensitive optionally specifies whether the search should be case sensitive. The


default is false.
Using this function on our example XML file as follows:


put revXMLMatchingNode(106,
"/", ,"name", "Hello", -1) \
into tMatch

This results in tMatch containing:
/stackFile/stack/card[1]/field

Retrieving an Outline of the Tree (or Portion Thereof)

To retrieve the contents of a specified node, use revXMLTree.

revXMLTree(treeID, startNode, nodeDelim, padding, \
includeChildCount, depth)


See above for an explanation of treeID, startNode, includeChildCount and depth.

The nodeDelim is
the delimiter that separates each node in the tree. Use return to retrieve
a list of nodes.
padding is the character to use
to indent each level in the tree.
Using this function on our example XML file as follows:
put revXMLTree(106
,"/",return,space,true,-1) into tTree
This results in tTree containing:


stackFile[1]

to:
set the defaultStack to "Other Stack"
put the hilite of button "Me" into meSetting-- this button is in "Other Stack"

set the defaultStack to savedDefault
set the hilite
of button "Me Too" to meSetting-- this button is in the original stack

If an object is in a group, you can include or omit a reference to the group in a nested
reference to
the object. For example, suppose the current card contains a button called
"Guido", which is part of a group called "Stereotypes". You can refer to the button with
any of the following expressions:

button "Guido"
button "Guido" of card 5
button
"Guido" of group "Stereotypes"
button "Guido" of group "Stereotypes" of card 5


If there is no other button named "Guido" on the card, these examples are equivalent. Ifthere is another button with the same name in another group (or on the card, but not in
any group), you must either specify
the group (as in the second and third examples) or
refer
to the button by its ID property, to be sure you're referring to the correct button.

7.2 Properties
A property is an attribute of a LiveCode object. Each type of object has many built-in
properties
, which affect the object's appearance or behavior. You can also define customproperties for any object, and use them to store any kind of data.

This topic discusses how to use properties, how properties are inherited between objects,
and how to create and switch between collections of property settings.

To fully understand this topic, you should know how to create objects, how to use an
object's property inspector, and how to write short scripts.

7.2.1 Using Object Properties
A property is an attribute of an object, and each object type has its own set of built-in
properties appropriate for that type. An object can be completely described by its built-in
properties; if you could make all the properties of two objects identical, they'd be thesame object. It is thus possible to describe an object entirely as an array of properties, or
to export and import properties using text or XML files. More details on some of themethods you can use to do this are covered later in this chapter.

Note: Since no two objects can have the same ID property, it's not possible in practicefor two different objects to become the same object, because the ID will always bedifferent.
Changed lines 1596-1646 from:
 stack[1]
card[1]
field[1]

 text[1]
htmlText[1]
card[2]


Retrieving the Tree as XML (or Portion Thereof)

To retrieve the tree as XML use revXMLText. Use this function to save the XML to a
file after modifying it.

revXMLText(treeID, startNode, [formatTree])

See above for an explanation of treeID and startNode.

The formatTree specifies whether or not
to format the returned tree with return and spacecharacters to make it easier to read by a human.

Using this function on our example XML file as follows:

ask file "Save XML as:"
put revXMLText(106
,"/",true) into URL ("file:" & it)

This results in the file
the user specifies containing:
<stackFile>
<stack name=
"Example" rect="117,109,517,509">
<card>
<field name="Hello" rect="100,100,200,125">
<text>Hello World!</text>
<htmlText>&lt;p&gt;Hello World&lt;/p&gt;</htmlText>
</field>
</
card>
<card/>
</
stack>
</stackFile>



Validating against a DTD

To check the syntax of an XML file conforms to
a DTD use revXMLValidateDTD.
For more information on this function, see the LiveCode Dictionary.

Listing all XML Trees in Memory

To generate a list of all XML trees in memory, use revXMLTrees. For more
information on this function, see the LiveCode Dictionary.

Removing an XML Tree from Memory

to:
Built-in properties determine the appearance and behavior of stacks and their contents-fonts,
colors, window types, size and placement, and much more – as well as much of thebehavior of the LiveCode application. By changing properties, you can change almostany aspect of your application. When you combine the ability to change properties with
the ability
to create and delete objects programmatically, you can modify every aspect ofyour application (subject to any limitations of the license agreement applicable to your
edition of LiveCode).

7.2.2 Referring to properties
Property references consist of the word the
, the property name, the word of, and a
reference to
the object:

the armedIcon of button
"My Button"
the borderWidth of field ID 2394
the name of
card 1 of stack "My Stack"

Properties are sources of value, so you can get the value of
a property by using it in an
expression:

put the height of field "Text" into myVarput the width of image "My Image" + 17 after field "Values"
if item 1 of the location of me > zero then beep

For example, to use the width property of a button as part of an arithmetic expression,
use a statement like the following:

add the width of button "Cancel" to totalWidths

The value of the property – in this case, the width of the button in pixels – is substituted
for the property reference when the statement is executed.
Tip: To see a list of all the language words (including properties) applicable to a
particular object type, open the Documentation window, click Dictionary, right-click on
the header bar to turn on the object type you want, then sort the list by clicking on thatobject header.
7.2.3 Changing properties
To change the value of a property, you use the set command:

set the borderColor of group "My Group" to "red"
set the top of image ID 3461 to zero

You can also see and change many of an object's properties by selecting the object and
choosing Object Inspector. See the chapter Building a User Interface for more details.

Changed lines 1635-1679 from:
To remove an XML tree from memory, use revDeleteXMLTree. To remove all XML
trees from memory
, use revDeleteAllXMLTrees. Both functions take a singleparameter – the ID of the tree to be deleted. You should delete a tree when you havestopped using it. For more information on these functions, see the LiveCode Dictionary.

Caution: Once an XML tree has been removed from memory, there is no way to get it

back. Use the revXMLText function to retrieve the contents of the entire tree and save it
first.
6.7.5 The XML Library: Editing XML
This section discusses how to edit XML trees. Before reading this section you should

read the section above on loading, displaying and unloading XML.

Adding a new Child Node

To add a new node use the revAddXMLNode command.

revAddXMLNode treeID, parentNode, nodeName, nodeContents, \
[location]

See above for an explanation of treeID
.
The parentNode is
the name of the node you want to add the child to.
The nodeName is the name of the new node to create.
nodeContents is the contents of the new node.
location - optionally specify "before" to place the new child at the start of
the child


nodes.
Use this function to add a button to our example XML file as follows:


revAddXMLNode 1, "/stackFile/stack/card/", "button", ""

This results in our tree containing a new button:

<?xml version="1.0" encoding="UTF-8"?>
<!-- This is a comment. -->
<stackFile>


<stack name="Example" rect="117
,109,517,509">
<card>


<field name="Hello" rect="100
,100,200,125">
<text>Hello World!</text>
<htmlText>&lt;p&gt;Hello World&lt;/p&gt;</htmlText>

to:
Most built-in properties affect the appearance or behavior of the object. For example, abutton's height, width, and location are properties of the button. Changing theseproperties in a handler causes the button's appearance to change. Conversely, dragging or
resizing the button changes the related properties.

Read-only properties

Some properties can be read, but not set. These are called read-only properties. Trying to
set a read-only property causes an execution error.


To find out whether a property is read-only, check its entry in the LiveCode Dictionary.

Changing a part of a property

Properties are not containers, so you cannot use a chunk expression to change a part of

the property. However, you can use a chunk expression to examine part of a property. For
example, you cannot set line 1 of a property to a new value: you must set the wholeproperty
. For more details see the section Chunk Expressions in the chapter on
Processing Text and Data
.

To change one part
of a property, first put the property value into a variable, change therequired part of the variable, then set the property back to the new variable contents:

put
the rect of me into tempRectput "10" into item 2 of tempRectset the rect of me to tempRect

Custom properties and virtual properties

A custom property is a property that you define. You can create as many customproperties for an object as you want
, and put any kind of data into them, including binary
data or array data. You can even store a file in a custom property.

Virtual properties are custom properties that trigger a custom script action when you
change them, allowing you to implement "virtual" object behaviors.

Custom properties and virtual properties are covered in their respective sections later in
this chapter.

7.2.4 Property Inheritance
Most properties are specific to the object they are part of, and affect only that object.

However, some properties of an object, such as its color and text font, take on the settingsof the object above it in the object hierarchy. For example, if a field's background color
property is not specified (that is, if its backgroundColor property is empty), the field
takes on the background color of the card that owns it. If no background color is specified
for the card either, the stack's background color is used, and so on. This means you can
set a background color for a stack, and every object in it will automatically use thatbackground color, without your having to set it for each object.

Changed lines 1677-1726 from:
</field>

 <button></button>
</card>
<card/>


</stack>
</stackFile>

To create another node at
the same level as another node, use the revInsertXMLNode
command instead.

Appending XML to a tree

To add a new node use the revAppendXML command.

revAppendXML treeID, parentNode, newXML

See above for an explanation of treeID and parentNode.
The newXML is XML you want to append
to the tree.

Moving, Copying or Deleting a Node

To move a node use the revMoveXMLNode command.

revMoveXMLNode treeID, sourceNode, destinationNode \
[, location] [, relationship]

See above for an explanation of treeID.
The sourceNode is the path to the node you want to move.
The destinationNode is the path to
the node you to move to.
The location specifies where
the node should be moved to in the list of siblings – it can


be either "before" or "after".


The relationship allows you to specify whether to place
the node alongside the
destination as a sibling or below the destination as a child
.
To copy a node use revCopyXMLNode.
To delete a node use revDeleteXMLNode.


Putting data into a Node

To put data into a node use the revPutIntoXMLNode command.

revPutIntoXMLNode treeID,node,newContents

to:
This process of first checking the object, then the object's owner, then the object that
owns that object, and so on, is called inheritance of properties. Each object inherits thebackground color of the object above it in the hierarchy. Similar inheritance rules apply
to the foregroundColor, topColor, bottomColor, borderColor,
shadowColor, and focusColor properties,
to their corresponding pattern properties,
and to the textFont, textSize, and textStyle properties.

7.2.5 Overriding inheritance
Inheritance is used to determine an object's appearance only if the object itself has no
setting for the property. If an inheritable property of an object is not empty, that setting
overrides any setting
the object might inherit from an object above it in the objecthierarchy.

For example, if a button's backgroundColor property is set to a color referenceinstead of being empty, the button uses that background color, regardless of the button'sowners. If
the object has a color of its own, that color is always used.

The effective keyword

If an inheritable property of an object is empty, you can't simply check the property to
find out what color or font settings the object displays. In this case, use the effective
keyword to obtain the inherited setting of the property. The effective keyword
searches the object's owners, if necessary, to find out what setting is actually used.

For example, suppose you have a field whose textFont property is empty. The
textFont of the card that the field is on is set to "Helvetica", so the field inherits thissetting and displays its text in the Helvetica font. To find out what font the field is using,
use the expression the effective textFont:

get the textFont of field "My Field" -- emptyget the effective textFont of field "My Field" -- Helvetica

You can use the effective keyword with any inherited property.

7.3 Global Properties
LiveCode also has global properties, which affect the overall behavior of the application.
Global properties are accessed and changed the same way as object properties. They do
not belong to any particular object, but otherwise they behave like object properties.

Tip: To see a list of all global properties, open the Message Box, and choose the Global
Properties icon – the third icon from the left at the top of the window. To see a list of all
properties in the language, including both global and object properties, use thepropertyNames global property.
Changed lines 1714-1758 from:
See above for an explanation of treeID and node.
The newContents is
the text that the new node will contain.


Setting an Attribute

To set an attribute use
the revSetXMLAttribute command.

revSetXMLAttribute treeID,node,attributeName,newValue

See above
for an explanation of treeID and node.
The attributeName is the name of the attribute you want to set
the attribute on.
The newValue is
the value to set for the attribute. 
Using this function to add a "showBorder" property to our field:


revSetXMLAttribute 1, \
"/stackFile/stack/card/button", "showBorder","true"

The field tag in our tree now looks like this:
<field name="Hello" rect="100,100,200,125" showBorder="true">


Adding a DTD

To add a DTD
to the tree, use the revXMLAddDTD command.

revXMLAddDTD treeID
,DTDText

See above for an explanation
of treeID.
The DTDText is the text of the DTD to add.

6.8 Sorting
Sorting data is a common and fundamental operation. Sorting allows you to display datain a user-friendly fashion or code
a number of algorithms. LiveCode's intuitive sort
features give you
the power and flexibility to perform any kind of sorting you may
require.

6.8.1 The Sort Container Command: Overview
To sort data, use the sort container command.

sort [{lines | items} of] container [direction] [sortType]
[by sortKey]

The container is a field, button, or variable, or the message box
.
to:
A few properties are both global and object properties. For example, the
paintCompression is a global property, and also a property of images. For theseproperties,
the global setting is separate from the setting for an individual object.

Some other global properties are affected by system settings. For example, the default
value of
the playLoudness property is set by the operating system's sound volume
setting.

7
.3.1 Referring to global properties
You refer to global properties using the and the property name:


the defaultFolder
the emacsKeyBindingsthe fileType

Since global properties apply to the whole application, you don't include an objectreference when referring
to them.

Global properties are sources of value
, so you can get the value of a global property by
using it in an expression:

get the stacksInUseput the recentNames into field "Recent Cards"
if the ftpProxy is empty then exit setMyProxy

7.3.2 Changing global properties
To change
a global property, you use the set command, in the same way as for object
properties:

set the itemDelimiter to "/"
set the grid to falseset the idleTicks to 10

Some global properties can be changed by other commands. For example, thelockScreen property can either be set directly, or changed using the lock screen
and unlock screen commands. The following two statements are equivalent:

set the lockScreen to false -- does the same thing as...
unlock screen

7.3.3 Saving and restoring global properties
Object properties are part of an object, so they are saved when the stack containing their
object is saved. Global properties, however, are not associated with any object, so they
are not saved with a stack. If you change the value of a global property, the change is lostwhen you quit the application
.
Changed lines 1754-1796 from:
The direction is either ascending or descending. If you don't specify a direction, the sort
is ascending.

The sortType is one of text, numeric, or dateTime. If you don't specify
a sortType, thesort is by text.

The sortKey is an expression that evaluates to a value for each line or item in thecontainer. If the sortKey contains a chunk expression
, the keyword each indicates that
the chunk expression is evaluated for each line or item. If you don't specify a sortKey, the
entire line (or item) is used as the sortKey.

The following example sorts the lines of a variable alphabetically:

sort lines
of field "sample text" ascending textsort lines of tText descending text

The following example sorts a collection
of items numerically:

sort items of field "sample csv" ascending numericsort items of tItems descending numeric

6.8.2 The Sort Container Command: Using Sort Keys
The sortKey syntax allows you to sort each line or item based on the results of an
evaluation performed on each line or item.

To sort the lines of a container by a specific item in each line:

sort lines of tContainer by the first item of eachsort lines of tContainer by item 3 of each

The sortKey expression will only be evaluated once for every element
that is to be sorted.
This syntax allows a variety of more complex sort operations to be performed.

The following example will extract the minimum and maximum integers present in a list:

set the itemDelimiter to "."
sort lines of fld 1 numeric by char 2 to -1
of the \
first item of each
put
char 2 to -1 of the first item of the first line \
of fld 1 into tMinimumIntegerput char 2 to -1 of the first item of the last line of \
fld 1 into tMaximumInteger

Original list:

Result:

F54.mov tMinimumInteger is 3

to:
If you want to use the same setting of a global property during a different session of your
application, you must save the setting – in a Preferences file, in
a custom property, or
elsewhere in a saved file – and restore it when your application starts up.

7.4 Text Related Properties
Normally, properties are applied only to objects or
, in the case of global properties, to theentire application. However, a few properties also apply to chunks in a field or to singlecharacters in a field.

7.4.1 Text style properties
Certain text-related properties can be applied either to an entire field or to a chunk
of afield:

set the textFont of word 3
of field "My Field" to "Courier"
set the foregroundColor of line 1
of field 2 to "green"
if the textStyle of the clickChunk is "bold" then beep

The following field properties can be applied to either an entire field or to a chunk of thefield:

textFont, textStyle, and textSize
textShift
backgroundColor and foregroundColorbackgroundPattern and foregroundPattern (Unix systems)

Each chunk of a field inherits these properties from the field, in the same way that fieldsinherit from their owners. For example, if a word's textFont property is empty, the
word is displayed in the field's font. But if you set the word's textFont to another font
name,
that word – and only that word – is displayed in its own font.

To find the text style of a chunk in a field, whether that chunk uses its own styles or
inherits them from the field, use the effective keyword:

get the effective textFont of word 3
of field ID 2355answer the effective backgroundColor of char 2 to 7 \

of field "My Field"

Tip: If a chunk expression includes more than one style, the corresponding property for
that chunk reports "mixed". For example, if the first line of a field has a textSize of "12",
and the second line has a textSize of "24", an expression like the textSize of line 1 to 2 of
field "My Field" reports "mixed".
Changed lines 1790-1831 from:
M27.mov

tMaximumInteger is 54

M7.mov
F3.mov

Figure 56 – Results
of sort command using sort key

6.8.3 The Sort Container Command: Sorting Randomly
To sort randomly, use the random function to generate a random number as
the sortKey
for each line or item, instead of evaluating the line or item's contents. For example:

put the number of lines of tExampleList into \
tElementCount
sort lines of tExampleList ascending numeric by \
random(tElementCount)

6.8.4 The Sort Container Command: Stable Sorts – Sorting onMultiple Keys
To sort a list by multiple criteria you can sort multiple times. This is because LiveCodeuses a stable sort, meaning that if two items have the same sort key their relative order in
the output will not change. To perform
a stable sort, start with the least significant or
important criteria
and work up to the most important or significant. For example:

sort lines of fld 1 ascending numeric by item 2 \
of each
sort lines of fld 1 ascending text by the \
first item of each

Original list:

Result:

Oliver,
1.54Elanor,5.67Elanor,5.67Elanor,6.34Marcus,8.99Marcus,8.99Elanor,6.34Oliver,1.54Oliver,8.99Oliver,8.99Tim,3.44 Tim,3.44

Figure 57 – Results
of sorting multiple items

Tip: If you have a large data set and want to improve performance by only performing a
single sort, you can construct a sort key that gives the appropriate ordering. In this
example a good way to do that is to use the format function to construct a fixed length
string, one element per sort:
Tip: sort lines of fld 1 ascending text by \
format("%-16s%08.2f", item 1 of each
, item 2 of each)
Tip: This formats each individual line similar to the following:
to:
7.4.2 Formatted text properties
The htmlText, RTFText, and unicodeText properties of a chunk are equal to thetext of that chunk, along with the formatting information that's appropriate for the
property.

For example, if a field contains
the text "This is a test.", and the word "is" is boldfaced,
the htmlText of word 2 reports "<b>is</b>".

For more information on these properties see the chapter on Processing Text and Data, as

well as the individual entries for these properties in the LiveCode Dictionary.

The formattedRect and related properties

The formattedRect property (along with the formattedWidth,
formattedHeight, formattedLeft, and formattedTop) reports the position
of a chunk of text in a field. These properties are read-only.

The formattedRect, formattedLeft, and formattedTop properties can be
used for
a chunk of a field, but not the entire field. The formattedWidth and
formattedHeight apply
to both fields and chunks of text in a field.

The imageSource, linkText, and visited properties

The imageSource of a character specifies an image to be substituted for that character

when the field is displayed. You use the imageSource to display images inside fields:

set the imageSource of char 17 of field
1 to 49232set the imageSource of char thisChar of field \

"My Field" to "http://www.example.com/banner.jpg"

The linkText property of a chunk lets you associate hidden text with part of a field'stext. You can use the linkText in a linkClicked handler to specify the destination
of a hyperlink, or for any other purpose.

The visited property specifies whether you have clicked on a text group during thecurrent session. You can get the visited property for any chunk in a field
, but it ismeaningless unless the chunk's textStyle includes "link".

The imageSource, linkText, and visited properties are the only properties thatcan be set to a chunk of a field, but not to the entire field or any other object. Becausethey are applied to text in fields, they are listed as field properties in the LiveCodeDictionary.

7.5 Creating and Deleting Objects
LiveCode allows you to create and delete objects programmatically. You may optionally
specify all the properties for a new object before creating it.

Changed lines 1831-1863 from:
Tip: Oliver 00001.54
Elanor 00005.67
Tip: These lines now sort the required way as if the first field (the
name) ties, the order is
determined by the second field – due to the use of padding characters making all the

fields the same size.
6.8.5 Sorting Cards
To sort cards, use the sort command.

sort [marked] cards [of stack] [direction] [sortType] bysortKey

The stack is a reference to
any open stack. If you don't specify a stack, the cards of thecurrent stack are sorted.

The direction is either ascending or descending. If you don't specify a direction, the sort
is ascending.


The sortType is one of text, international, numeric, or dateTime. If you don't specify asortType, the sort is by text.


The sortKey is an expression that evaluates to a value for each card
in the stack. Any
object references within the sortKey are treated as pertaining to each card being
evaluated
, so for example, a reference to a field is evaluated according to that field'scontents on each card. Typically the sort command is used with background fields that
have their sharedText property set to false so that they contain a different value on each
card.

For example to sort cards by
the contents of the last name field on each:

sort cards by field "Last Name"

To sort cards by
the numeric value in a ZIP Code:

sort cards numeric by field "ZIP code"

Tip: To sort cards by a custom expression that performs a calculation
, you can create acustom function:
Tip: sort cards by myFunction() -- uses function below
to:
7.5.1 The Create Object Command
You use the create command to create a new object.

create [invisible] type [
name] [in group]

The type
is any control that can be on a card: field, button, image, scrollbar, graphic,
player, or EPS.


The name is the name of the newly created object. If you don't specify a name, the object

is created with a default name.

The group is
any group that's on the current card. If you specify a group, the new objectis a member of the group, and exists on each card that has the group. If you don't specify
a group, the object is created on the current card and appears only on that card.

create button "Click Me"

create invisible field in first group

For more details, see the create command
in the LiveCode Dictionary. For details on how
to specify the properties of an object before creating it
, see the section on Creating
Objects Off-screen Using Template Objects, below.

7.5.2 The Delete Object Command
You can use
the delete command to remove objects from the stack.

delete {object}

The object is any available object.

delete this card
delete button "New Button"

For more details, see the delete command in
the LiveCode Dictionary.

7.5.3 Creating Objects Off-screen Using Template Objects
LiveCode uses template objects to allow you to specify
the properties for an object beforeit is created. The template objects are off-screen models – there is one for each possibletype of object, e.g. button, field, graphic, etc.

If you need to create a new object and then set some properties on the object, it is moreefficient to make the changes to the template object, then create the object. Because theobject can be created with all of its properties set correctly, there is no need to lock thescreen and update or reposition the object after creating it. For example, the LiveCodedevelopment environment uses the template objects internally to create new objects fromthe main tool palette.

Changed lines 1870-1872 from:
Tip: function myFunctionput the number of buttons of this card into tValue-- perform any calculation on tValue herereturn tValue
-- sort will use this value
end myFunction
to:
You set properties on template objects in the same way you set properties on normalobjects.

set the {property} of the template{Objecttype} to {value}

For example, to create a button with the name "Hello World", positioned at 100,100:

set the name of the templateButton to "Hello World"
set the location of the templateButton to 100,100create button

When you have used the templateObject to create a new object, you should reset it beforeusing it again. Resetting the templateObject sets all off its properties back to defaults.

reset the template[Objecttype]

For example, to reset the templateButton:
reset the templateButton

For more details on the template objects, search the LiveCode Dictionary for "template".

7.6 Property Arrays using the Properties Property
In addition to retrieving individual object properties, you can retrieve or set an entire setas an array using the properties property. You can use this to edit, copy, export or
import properties.

set the properties of object to propertiesArrayput the properties of object into propertiesArray

The properties of an object is an array containing that object's significant built-in
properties.

put the properties of button 1 into myArrayset the properties of last player to the properties \

of player "Example"

Tip: This example handler shows you how to write the properties of an object to a text
file.
Tip: on mouseUpput the properties of button 1 into tPropertiesArray
combine tPropertiesArray using return and "|"
ask file "Save properties as:"
if it is not empty then put tPropertiesArray into \
Changed lines 1908-1919 from:
Chapter 7 Programming a User Interface

The user interface for your application is often one of its most important features. In

Chapter 4 we looked at how you build a user interface using LiveCode’s tools and
development environment. In this chapter we look at how you can edit, or even build auser interface programmatically. Everything you can do using the built-in tools you
can
also do programmatically. You can even create and modify a user interface at run time
in
a standalone application, or provide interactive methods for your users to modify specificaspects of your application. This set of capabilities allow
you to produce applications thatconstruct their interface using XML files or a custom data structure, programmatically
construct aspects of complex interfaces
, modify their look using user specified
parameters, create themed or skinned interface options, build your own interface editing
tools that plug-in
to LiveCode’s IDE and much more. You can also create custom objectsand attach your own virtual behaviors and custom properties to them. We recommend
you spend a little time becoming familiar with building an interface using the tools in thedevelopment environment before creating or editing an interface programmatically.

to:
URL ("file:" & it)
end mouseUp
Tip: In this example, each property name will be written followed by the "|" character

and the property value and then a return character.
For more details, see the properties property in the LiveCode Dictionary.

7.7 Property Profiles
A property profile is a collection of object property settings, which is stored as a set. Aprofile for an object
can contain settings for almost any properties of the object.

You can include values for most built-
in properties in a profile, and create as many
different property profiles as you need for any object. Once you've created a profile,
you
can switch the object to the profile to change all the property values that are defined in
the profile.

For example
, suppose you create a property profile for a field that includes settings for
the field's color properties. When you switch
to that profile, the field's colors change,
while all other properties (not included in the profile) remain the same.

Use property profiles when you want to:
Create "skins" for your applicationDisplay your application in different languagesPresent different levels--"novice","expert", and so onUse different user-interface standards for different platforms

For details on how to create property profiles using the IDE, see the section on Property
Profiles in the chapter Building a User Interface.

7.7.1 Profile names
Profile names follow the same rules as variable names. A profile name must be a singleword, consisting of letters, digits, and underscores, and must start with either a letter or
an underscore.
Tip: If you want to use a single command to switch several objects to a particular profile,
give the profile the same name for each of the objects it applies to.
7.7.2 The master profile
Every object has a master profile that holds the default settings for all its properties. Ifyou don't set an object's profile, the master profile is used. When you create a newprofile, you can change settings for various properties to make them different from themaster profile's settings
.
Changed lines 1941-1978 from:
7.1 Referring to Objects
In general, you can refer to any object by its name, number, or ID property.

7.1.1 Referring
to objects by name
You can refer to an object using its object type followed by its name
. For example, to
refer to a button
named "OK", use the phrase button "OK":

set the loc of button "OK" to 32,104

To change an object's name, enter
a name in the object's property inspector, or use the
set command to change
the object's name property:

set
the name of field "Old Name" to "New Name" 
select after text of field "New Name"

7.1.2 Referring to objects by number
A control's number is its layer
on the card, from back to front. A card's number is itsposition in the stack. A stack's number is the order of its creation in the stack file. A main
stack's number is always zero.


You can refer to an object using its object type followed by its number. For example, to
refer to
the third-from-the-back field on a card, use the phrase field 3:

set the backgroundColor of field 3 to blue

To change the number of a card or control, change the Layer box in the Size & Position
pane
of the object's property inspector, or use the set command to change the object's
layer property:

set the layer of field "Backmost" to 1

Tip: New objects are always created at the top layer.
To refer to an object you've justcreated, use the ordinal last:
Tip: create button
set the name of last button to
"My New Button"
7.1.3 Referring to objects by ID
Each object in LiveCode has an ID number. The ID property never changes (except for
stack IDs), and is guaranteed unique within the stack: no two objects in the same stack
can have the same ID property
.
to:
If you don't specify a property setting in a profile, the master profile's setting is used, so
you don't have
to specify all properties of an object when you create a profile--only theones you want to change.

By default
, the master profile is named "Master". You can change the master profile's
name in the Property Profiles pane of the Preferences window.

7.7.3 Switching between profiles
Switching
a single object

To switch an object's profile, you can use either
the object's property inspector or the
revProfile property.

set the revProfile of player
"My Player" to "MyProfile"

Switching all the objects on a card

To switch the profiles of all the objects
on a card, use the revSetCardProfile
command:

revSetCardProfile "MyProfile","My Stack"

The statement above sets
the profile of all objects on the current card of the stack named
"My Stack". (Although the revSetCardProfile command changes a card, you

specify a stack name, not a card name.)

If an object on the card does not have a profile with
the specified name, the object is leftuntouched.

Switching all the objects in a stack

To switch the profiles of all the objects in a stack, use the revSetStackProfile
command:

revSetStackProfile "MyProfile","My Stack"

The statement above sets the profile
of all objects in the stack named "My Stack".

If an object in
the stack does not have a profile with the specified name, the object is leftuntouched.

Switching all the objects in a stack file

To switch the profiles of all the objects in every stack in a stack file, use therevSetStackFileProfile command:

revSetStackFileProfile
"MyProfile","My Stack"

The statement above sets the profile of all objects in the stack named "My Stack", along
with any other stacks in the same stack file.

Changed lines 1989-2027 from:
You can refer to an object using its object type, then keyword ID, followed by its ID
number. For example, to refer to
a card whose ID property is 1154, use the phrase card
ID 1154:

go to card ID 1154

You cannot change an object's ID property (except for a stack).

Important: Wherever possible, you should name your objects and refer to them by
name instead of using number or ID. Both the number and ID properties will change ifobjects are copied and pasted. Additionally, your scripts will rapidly become difficult to
read if there are many ID or numerical references to objects.
7.1.4 Referring to objects by ordinal
You can refer
to an object using its object type followed by the ordinal numbers first
through tenth, or the special ordinals middle and last. To refer to a random object,
use the special ordinal any. For example,
to refer to the last card in the current stack, use
the special ordinal last:

go to last card

7
.1.5 The special descriptor .this'
Use the this keyword to indicate the current stack, or the current card of a stack:

set the backgroundColor of this stack to whitesend "mouseUp" to this cardset the textFont of this card of stack "Menubar" to
"Sans"

7.1.6 Control references
A control is any object that can appear on a card. Fields, buttons, scrollbars, images,
graphics, players, EPS objects, and groups are all controls. Stacks, cards, audio clips,
and
video clips are not controls.

You can refer to an object of any of these object types using the word "control", followed
by an ID, name, or number:

hide control ID 2566
send mouseDown to control "My Button"
set the hilite of control 20 to false

If you use a name, as in the expression control "Thing", the reference is to the
first control (with the lowest layer) that has that name
.
to:
If an object in any of the stacks does not have a profile with the specified name, theobject is left untouched.

7.7.4 Creating
a profile in a handler
In addition to creating property profiles in the property inspector, you can create a profilein a handler.

To enable creating profiles, check the "Create profiles automatically" box in the"Property Profiles" pane of the Preferences window. If this box is checked, setting therevProfile property of an object automatically creates the profile.

This ability is particularly useful if you want to create a number of profiles, as shown in
the following example:

on mouseUp

-- creates a profile for each card in the stack

 repeat with thisCard = 1
to the number of cards

set the revProfile of card x to "myNewProfile"
end repeatend mouseUp

The handler above creates a profile called "myNewProfile" for all the cards in the currentstack.

In order for this handler
to work, the "Create profiles automatically" option in the"Property Profiles" pane of the Preferences window must be turned on. 

You can control
this behavior either in Preferences window or using thegRevProfileReadOnly keyword. If you don't want to save property changes when
switching profiles, do one of the following:

Set the gRevProfileReadOnly variable to true:

global gRevProfileReadOnlyput true into gRevProfileReadOnly

In the
"Property Profiles" pane of the Preferences window, uncheck the box labeled
"Don't save changes in profile".

The two methods of changing this setting are equivalent: changing thegRevProfileReadOnly variable also changes the preference setting,
and vice versa.

For more details, see gRevProfileReadOnly in the LiveCode Dictionary.

Changed lines 2027-2066 from:
When you refer to a control by number using its object type, the reference is to the Nth
control of that type. For example, the phrase field
1 refers to the lowest field on the
card. This may not be the lowest control, because there may be controls of other typesunderneath field 1. However, when you refer to a control by number using the word
control,
the reference is to the Nth control of any type. The phrase control 1
refers to the lowest control on the card, which may be of any type.

Tip: To refer to the object underneath the mouse pointer, use the mouseControl
function.
7.1.7 Nested Object References
To refer to an object that belongs
to another object, nest the references in the same order
as the object hierarchy. For example, if there is a button called "My Button" on a card

called "My Card", you can refer to the button like this:

show button "My Button" of card "My Card"

You can mix names, numbers, ordinal references
, and IDs in a nested object reference,
and you can nest references to whatever depth is required to specify the object
. The only
requirement is that the order of references be the same as the order of
the objecthierarchy, going from an object to the object that owns it. Here are some examples:

field ID 34 of card "Holder"
player 2 of group "Main" of card ID 20 of stack "Demo"
first card of this stack
stack "Dialog" of stack "Main" -- "Dialog" is a substack


If you don't specify a card in referring to an object that is contained by
a card, LiveCodeassumes the object is on the current card. If you don't specify a stack, LiveCode assumesthe object is in the current stack. You can reference a control in another stack by either ofthe following methods:

Use a nested reference that includes the name of the stack:

field 1 of stack "My Stack"
graphic "Outline"
of card "Tools" of stack "Some Stack"


Set the defaultStack
property to the stack you want to refer to first. The
defaultStack specifies the current stack, so you can refer to any object in the
defaultStack without including a stack name. This example sets a checkbox in thecurrent stack to have the same setting as a checkbox in another stack called "Other
Stack":

put the defaultStack into savedDefault-- so you can set it back later

to:
7.7.5 Adding profile settings in a handler
You can add a property setting to a profile by switching
to the profile, then setting theproperty:

set the revProfile of button
1 to "MyProfile"
set
the foregroundColor of button 1 to "red"
set the revProfile of button 1 to "Master"

By default, if you change a property and then switch profiles, the property you changed
and its current setting is saved with
the profile.

7.8 Custom Properties
A custom property is a property that you create for an object, in addition to its built-in
properties. You can define custom properties for any object, and use them to store any
kind of data.

This topic discusses how to create and use custom properties, and how
to organize
custom properties into sets (or arrays). The following section covers how to create virtual
properties and use getProp and setProp handlers to handle custom property

requests.

7.8.1 Using Custom Properties
A custom property is a property that you define. You can create as many customproperties for an object as you want
, and put any kind of data into them (even binary
data). You can even store a file in a custom property
.

Use a custom property when you want to:

*
associate data with a specific object
*
save
the data with the object in the stack file
*
access the data quickly
7.8.2 Creating a Custom Property
You create a custom property by setting the new property to a value. If you set a customproperty that doesn't exist, LiveCode automatically creates the custom property and sets itto the requested value.

This means that you can create a custom property in
a handler or the message box, simply
by using the set command. The following statement creates a custom property called
"endingTime" for a button:

set the endingTime of button "Session" to the long time

You can create custom properties for any object. However, you cannot create globalcustom properties, or custom properties for a chunk
of text in a field. Unlike some builtin
properties, a custom
property applies only to an object.
Changed lines 2072-2108 from:
set the defaultStack to "Other Stack"
put the hilite of button "Me" into meSetting-- this button is in "Other Stack"
set the defaultStack to savedDefault
set the hilite of button "Me Too" to meSetting-- this button is in
the original stack

If an object is in a group, you can include or omit a reference to
the group in a nested
reference to
the object. For example, suppose the current card contains a button called
"Guido", which is part of a group called "Stereotypes". You can refer to
the button with
any of
the following expressions:

button "Guido"
button "Guido" of card 5
button "Guido" of group "Stereotypes"
button "Guido"
of group "Stereotypes" of card 5


If there is no other button named "Guido" on the card, these examples are equivalent. Ifthere is another button with the same name in another group (or on
the card, but not in
any group), you must either specify the group (as in the second and third examples) or
refer to the button by its ID property,
to be sure you're referring to the correct button.

7.2 Properties
A
property is an attribute of a LiveCode object. Each type of object has many built-in
properties
, which affect the object's appearance or behavior. You can also define customproperties for any object, and use them to store any kind of data.

This topic discusses how
to use properties, how properties are inherited between objects,
and how to create and switch between collections
of property settings.

To fully understand this topic, you should know how to create objects, how to use an
object's property inspector, and how to write short scripts.

7.2.1 Using Object Properties
A property is an attribute of an object, and each object type has its own set of built-in
properties appropriate for that type. An object can be completely described by its built-in
properties; if you could make all the properties of two objects identical, they'd be thesame object. It is thus possible to describe an object entirely as an array of properties, or
to export and import properties using text or XML files. More details on some of themethods you can use to do this are covered later in this chapter.

Note: Since no two objects can have the same ID property, it's not possible in practicefor two different objects to become the same object, because the ID will always bedifferent
.
to:
Important: Each object can have its own custom properties, and custom properties arenot shared between objects. Creating a custom property for one object does not create it
for other objects.

7.8.3 The Content of a Custom Property
You set
the value of a custom property by using its property name together with the set
command, in
the same way you set built-in properties:

set
the myCustomProperty of button 1 to false

You can see and change all of an object's custom properties in the Custom Properties
pane of
the object's property inspector: click the custom property you want to change,
then enter the new value.

Changing a part
of a property

Like built-in properties, custom properties are not containers, so you cannot use a chunk
expression to change a part of the custom property. Instead, you put the property's valueinto a variable and change
the variable, then set the custom property back to the newvariable contents:

put the lastCall of this card into myVarput "March" into word 3 of myVarset the lastCall of thisCard
to myVar

7.8.4 Custom Property Names
The name of a custom
property must consist of a single word and may contain any
combination of letters, digits
, and underscores (_). The first character must be either aletter or an underscore.

Avoid giving a custom property the same name as a variable
. If you refer to a customproperty in a handler, and there is a variable by the same name, LiveCode uses thecontents of the variable as the name of the custom property. This usually causesunexpected results.

Important: It is important to avoid giving custom properties the same name as existingengine properties unless those properties are only ever accessed in the context of a
custom property set. Unintended effects may result if you attempt to use the name of an
engine property as a custom property.
Changed lines 2101-2138 from:
Built-in properties determine the appearance and behavior of stacks and their contents-fonts,
colors, window types, size and placement, and much more – as well as much of thebehavior of
the LiveCode application. By changing properties, you can change almostany aspect of your application. When you combine the ability to change properties with
the ability to create and delete objects programmatically, you can modify every aspect ofyour application (subject to any limitations of the license agreement applicable to your
edition of LiveCode).

7.2.2 Referring to properties
Property references consist of the word the, the property name
, the word of, and a
reference to
the object:

the armedIcon of button "My Button"
the borderWidth of field ID 2394
the name of card 1 of stack "My Stack"

Properties are sources of value
, so you can get the value of a property by using it in an
expression:

put
the height of field "Text" into myVarput the width of image "My Image" + 17 after field "Values"
if item 1 of the location of me > zero then beep

For example, to use
the width property of a button as part of an arithmetic expression,
use
a statement like the following:

add the width of button "Cancel" to totalWidths

The value of the
property in this case, the width of the button in pixels – is substituted
for
the property reference when the statement is executed.
Tip: To see a list of all the language words (including properties) applicable to a
particular object type, open
the Documentation window, click Dictionary, right-click on
the header bar to turn on the object type you want, then sort the list by clicking on thatobject header.
7
.2.3 Changing properties
To change the value of
a property, you use the set command:

set the borderColor of group "My Group" to "red"
set the top of image ID 3461 to zero

You can also see and change many of an object's properties by selecting the object and
choosing Object Inspector. See the chapter Building a User Interface for more details
.
to:
Important: Custom property names beginning with "rev" are reserved for LiveCode's
own custom properties. Naming a custom property with a reserved name may produceunexpected results when working in
the development environment.
7.8.5 Referring to Custom Properties
Custom property references look just like built-in property references:
the word the, the
property name,
the word of, and a reference to the object.

For example, to use a custom property called "lastCall" that belongs to a card, use a

statement like the following:

put the lastCall of this card into field "Date"

Like built-in properties
, custom properties are sources of value, so you can get the valueof a custom property by using it in an expression. The property's value is substituted for
the property reference when the statement is executed. For example
, if the card's"lastCall" custom property is "Today", the example statement above puts the string
"Today" into the "Date" field.

7.8.6 Nonexistent Custom Properties
Custom properties that don't exist evaluate to empty. For example,
if the current card
doesn't have a custom property called "astCall", the following statement empties thefield:

put
the lastCall of this card into field "Date" – empty

Note: Referring to
a nonexistent custom property does not cause a script error. This
means that if you misspell a custom
property name in a handler, you won't get an error
message, so you might not notice
the problem right away.
7.8.7 Finding out Whether a Custom Property Exists
The customKeys property of an object lists the object's custom properties, one per line:

put
the customKeys of button 1 into field "Custom Props"

To find out whether a custom property for an object exists, you check whether it's listed
in the object's customKeys
. The following statement checks whether a player has acustom property called "doTellAll":

if "doTellAll" is among the lines of the customKeys \
of player "My Player" then...

Changed lines 2137-2177 from:
Most built-in properties affect the appearance or behavior of the object. For example, abutton's height, width, and location are properties of the button. Changing theseproperties in a handler causes the button's appearance to change. Conversely, dragging or
resizing the button changes the related properties.

Read-only properties

Some properties can be read, but not set. These are called read-only properties. Trying to

set a read-only property causes an execution error.

To find out whether a property is read-only, check its entry
in the LiveCode Dictionary.

Changing a part of a property

Properties are not containers, so you cannot use a chunk expression to change a part of
the property. However, you can use a chunk expression to examine part of a property. For
example
, you cannot set line 1 of a property to a new value: you must set the wholeproperty. For more details see the section Chunk Expressions in the chapter on
Processing Text and Data.

To change one part of a property, first put the property value into a variable, change therequired part
of the variable, then set the property back to the new variable contents:

put the rect of me
into tempRectput "10" into item 2 of tempRectset the rect of me to tempRect

Custom properties and virtual properties

A custom property is a property that you define. You can create as many customproperties for an object as you want, and put any kind of data into them, including binary
data or array data. You can even store
a file in a custom property.

Virtual properties are custom properties that trigger a custom script action when you
change them, allowing you to implement "virtual" object behaviors.

Custom properties and virtual properties are covered in their respective sections later in
this chapter.

7.2.4 Property Inheritance
Most properties are specific to the object they are part
of, and affect only that object.

However, some properties of an object, such as its color and text font
, take on the settingsof the object above it in the object hierarchy. For example, if a field's background color
property is not specified (that is, if its backgroundColor
property is empty), the field
takes on the background color of
the card that owns it. If no background color is specified
for the card either, the stack's background color is used, and so on. This means you can
set a background color for a stack, and every object in it will automatically use thatbackground color, without your having to set it for each object.

to:
You can also look in the Custom Properties pane of the object's property inspector, which
lists the custom
properties. See the chapter on Building a User Interface for more details.

7
.8.8 Custom Properties & Converting Text Between Platforms
When you move a stack developed on a Mac OS or OS X system to a Windows or Unix
system (or vice versa), LiveCode automatically translates text in fields and scripts into
the appropriate character set. However, text
in custom properties is not converted
between the ISO and Macintosh character sets. This is because custom properties can
contain binary data as well as text, and converting them would garble the data.

Characters whose ASCII value is between 128 and 255
, such as curved quotes and
accented characters, do not have the same ASCII
value in the Mac OS character set and
the ISO 8859-1 character set used on Unix and Windows systems. If such a character isin a field, it is automatically translated, but it's not translated if it's in a custom property.

Because
of this, if your stack displays custom properties to the user--for example, if thestack puts a custom property into a field--and if the text contains special characters, itmay be displayed incorrectly if you move the stack between platforms. To avoid thisproblem, use one of these methods:

Before displaying the custom property, convert it to the appropriate character set using
the macToISOor ISOToMac function. The following example shows how to convert acustom property that was created on
a Mac OS system, when the property is displayed on
a Unix or Windows system:

if the platform is "MacOS" then

 answer the myPrompt of button 1else

 answer macToISO(the myPrompt of button 1)
end if

Instead of storing the custom property as text, store it as HTML, using the HTMLText
property of fields:

set the myProp
of this card to the HTMLText of field 1

Because the HTMLText property encodes special characters as entities
, it ensures thatthe custom property does not contain any special characters--only the platformindependent
encodings for them. You can then set a field's HTMLText to the contents of
the custom
property to display it:

set the HTMLText of field "Display" \
to
the myProp of this card

7.8.9 Storing a file in a custom property
You can use a URL to store a file's content in a custom property:

Changed lines 2180-2215 from:
This process of first checking the object, then the object's owner, then the object that
owns that object, and so on, is called inheritance of properties. Each object inherits thebackground color of the object above it in the hierarchy. Similar inheritance rules apply
to the foregroundColor, topColor, bottomColor, borderColor,
shadowColor, and focusColor properties, to their corresponding pattern properties,
and to the textFont, textSize, and textStyle properties.


7.2.5 Overriding inheritance
Inheritance is used to determine an object's appearance only if the object itself has no
setting for the property. If an inheritable property of an object is not empty, that setting
overrides any setting the object might inherit from an object above it in the objecthierarchy.

For example, if a button's backgroundColor property is set to a color referenceinstead of being empty
, the button uses that background color, regardless of the button'sowners. If the object has a color of its own, that color is always used.

The effective keyword

If an inheritable property of an object is empty, you can't simply check
the property to
find out what color or font settings
the object displays. In this case, use the effective
keyword to obtain the inherited setting of the property. The effective keyword
searches the object's owners, if necessary, to find out what setting is actually used.

For example, suppose you have a field whose textFont property is empty. The
textFont of
the card that the field is on is set to "Helvetica", so the field inherits thissetting and displays its text in the Helvetica font. To find out what font the field is using,
use the expression the effective textFont:

get the textFont of field "My Field" -- emptyget the effective textFont of field "My Field" -- Helvetica

You can use the effective keyword with any inherited property.

7.3 Global Properties
LiveCode also has global properties, which affect the overall behavior of the application.
Global properties are accessed and changed the same way as object properties. They do
not belong to any particular object, but otherwise they behave like object properties.

Tip: To see a list of all global properties, open the Message Box, and choose the Global
Properties icon – the third icon from the left at the top of the window. To see a list of all
properties in the language, including both global and object properties, use thepropertyNames global property.
to:
set the myStoredFile of stack "My Stack" \
to URL "binfile:mypicture.jpg"

You restore
the file by putting the custom property's value into a URL:

put the myStoredFile of stack "My Stack" \
into URL "binfile:mypicture.jpg"

Because a custom property can hold any kind of data, you can store either text files or
binary files in a custom property. You can use this capability to bundle media files or

other files in your stack.

Many Mac OS Classic files have a resource fork. To store and restore such a file, you can
use the resfile URL scheme to store the content of the resource fork separately.

Tip: To save space, compress the file before storing it:
Tip: set the myStoredFile of stack "My Stack" \
to compress(URL "binfile:mypicture.jpg")
Tip: When restoring the file
, decompress it first:
Tip: put decompress(the myStoredFile
of stack "My Stack") \
into URL "binfile:mypicture.jpg"
For more information about using URL containers, see the chapter on Working with
Files, URLs and Sockets.

7.8.10 Deleting a custom property
As described above,
the customKeys property of an object is a list of the object's
custom properties
. You can set the customKeys of an object to control which custom
properties it has.

In LiveCode, there is no command to delete a custom property. Instead, you place all thecustom property names in a variable, delete the one you don't want from that variable,
and set
the object's customKeys back to the modified contents of the variable. This
removes
the custom property whose name you deleted.

For example,
the following statements delete a custom property called
"propertyToRemove" from the button "My Button":

get
the customKeys of button "My Button"
set the wholeMatches to true

delete line lineOffset("propertyToRemove",it) of it
Changed lines 2221-2259 from:
A few properties are both global and object properties. For example, the
paintCompression is
a global property, and also a property of images. For theseproperties, the global setting is separate from the setting for an individual object.

Some other global properties are affected by system settings. For example, the default
value
of the playLoudness property is set by the operating system's sound volume
setting.

7.3.1 Referring to global properties
You refer to global properties using the and the
property name:

the defaultFolder
the emacsKeyBindingsthe fileType

Since global properties apply to the whole application,
you don't include an objectreference when referring to them.

Global properties are sources of value, so you can get
the value of a global property by
using it in an expression:

get the stacksInUseput the recentNames into field "Recent Cards"
if the ftpProxy is empty then exit setMyProxy

7.3.2 Changing global properties
To change a global property, you use
the set command, in the same way as for object
properties:

set the itemDelimiter to "/"
set the grid to falseset the idleTicks to 10


Some global properties can be changed by other commands. For example, thelockScreen property can either be set directly, or changed using the lock screen
and unlock screen commands. The following two statements are equivalent:

set
the lockScreen to false -- does the same thing as...
unlock screen

7.3.3 Saving and restoring global properties
Object properties are part of an object,
so they are saved when the stack containing their
object is saved. Global properties, however, are not associated with any object, so they
are not saved with a stack. If you change
the value of a global property, the change is lostwhen you quit the application.
to:
set the customKeys of button "My Button" to it

You can also delete
a custom property in the Custom Properties pane of the object's
Property Inspector. Select the property's name and click
the Delete button to remove it.

7.9 Custom Property Sets
Custom
properties can be organized into custom property sets – or arrays of customproperties. A custom property set is a group of custom properties that has a name you
specify.

When you refer to a custom
property, LiveCode looks for that property in the object's
currently-active custom property set. When
you create or set a custom property,
LiveCode creates it in the currently-active custom property set, or sets
the value of thatproperty in the currently-active set. One custom property set is active at any one time, butyou can use array notation to get or set custom properties in sets other than the currentset.

The examples in
the previous section assume that you haven't created any customproperty sets. If you create a custom property without creating a custom property set for
it, as shown in the previous examples, the new custom property becomes part of theobject's default custom property set.

7.9.1 Creating custom property sets
To make a custom property set active, you set the object's customPropertySetproperty to
the set you want to use. As with custom properties and local variables, if thecustom property set you specify doesn't exist, LiveCode automatically creates it, so you
can create a custom property set for an object by simply switching to that set.

The following statement creates a custom property set called "Alternate" for an object,
and makes it
the active set:

set the customPropertySet of
the target to "Alternate"

The statement above creates the custom property set.

You can also view, create, and delete custom property sets in the Custom pane of theobject's property inspector.

You can list all the custom property sets of an object using its customPropertySetsproperty.

As with custom properties, you can create custom property sets for any object. But you
can't create global custom property sets, or custom property sets for a chunk of a field
.
Changed lines 2256-2290 from:
If you want to use the same setting of a global property during a different session of your
application, you must save the setting – in a Preferences file, in
a custom property, or
elsewhere in a saved file – and restore it when your application starts up.

7.4 Text Related Properties
Normally, properties are applied only to objects or, in the case of global properties, to theentire application. However,
a few properties also apply to chunks in a field or to singlecharacters in a field.

7.4.1 Text style properties
Certain text-related properties can be applied either
to an entire field or to a chunk of afield:

set the textFont of word 3 of field "My Field" to "Courier"
set the foregroundColor of line 1 of field 2
to "green"
if
the textStyle of the clickChunk is "bold" then beep

The following field properties can be applied to either an entire field or to a chunk of thefield:

textFont, textStyle, and textSize
textShift

backgroundColor and foregroundColorbackgroundPattern and foregroundPattern (Unix systems)

Each chunk of a field inherits these properties from the field, in the same way that fieldsinherit from their owners
. For example, if a word's textFont property is empty, the
word is displayed in the field's font. But if you
set the word's textFont to another font
name, that word – and only
that word – is displayed in its own font.

To find the text style of
a chunk in a field, whether that chunk uses its own styles or
inherits them from the field, use the effective keyword:

get
the effective textFont of word 3 of field ID 2355answer the effective backgroundColor of char 2 to 7 \

of field "My Field"

Tip: If a chunk expression includes more than one style,
the corresponding property for
that chunk reports "mixed". For example, if the first line of a field has a textSize of "12",

and the second line has a textSize of "24", an expression like the textSize of line 1 to 2 of
field "My Field" reports "mixed".
to:
7.9.2 Custom property set names
The names of custom property sets should consist of
a single word, with any combination
of letters, digits, and underscores (_). The first character should be either
a letter or an
underscore.

It is possible to create a custom property set with a name that has more than one word, or
that otherwise doesn't conform to these guidelines. However, this is not recommended,
because such
a custom property set can't be used with the array notation described below.

Note: When you use the Custom Properties pane in the property inspector
to create a
custom property set, the pane restricts you to these guidelines.
7.9.3 Referring to custom property sets
To switch the active custom property set, set the object's customPropertySet property
to
the name of the set you want to use:

set the customPropertySet of button 3 to "Spanish"

Any references to custom property refer to the current custom property set. For example,

suppose you have two custom property sets named "Spanish" and "French", and theFrench set includes a custom property called "Paris" while the Spanish set does not. Ifyou switch to the Spanish set, the customKeys of the object does not include "Paris",
because the current custom property
set doesn't include that property.

If you refer to a custom property
that isn't in the current set, the reference evaluates to
empty. If you set
a custom property that isn't in the current set, the custom property iscreated in the set. You can have two custom properties with the same name in differentcustom property sets, and they don't affect each other: changing one does not change theother.

The customProperties property of an object includes only the custom propertiesthat are in
the current custom property set. To specify the customProperties of a
particular custom property set, you include the set's name in square brackets:


put
the customProperties[mySet] of this card into myArray

7.9.4 Finding out whether a custom property set exists
The customPropertySets property
of an object lists the object's custom property
sets, one per line:

answer the customPropertySets of field "My Field"

Changed lines 2292-2331 from:
7.4.2 Formatted text properties
The htmlText, RTFText, and unicodeText properties of a chunk are equal to thetext of that chunk, along with the formatting information that's appropriate for the
property.

For example, if a field contains the text
"This is a test.", and the word "is" is boldfaced,
the htmlText of word 2 reports "<b>is</b>".

For more information on these properties see the chapter on Processing Text and Data, as
well as
the individual entries for these properties in the LiveCode Dictionary.

The formattedRect and related properties

The formattedRect
property (along with the formattedWidth,
formattedHeight, formattedLeft, and formattedTop) reports
the position
of a chunk of text in a field. These properties are read-only.

The formattedRect, formattedLeft, and formattedTop properties can be
used for
a chunk of a field, but not the entire field. The formattedWidth and
formattedHeight apply to both fields and chunks of text in a field.

The imageSource, linkText, and visited properties

The imageSource of a character specifies an image to be substituted for that character

when the field is displayed. You use the imageSource to display images inside fields:

set the imageSource of char 17 of field 1 to 49232set the imageSource of char thisChar of field \

"My Field" to "http
://www.example.com/banner.jpg"

The linkText property of a chunk lets you associate hidden text with part of a field'stext. You can use the linkText in a linkClicked handler to specify the destination
of a hyperlink, or for any other purpose.

The visited property specifies whether you have clicked on a text group during thecurrent session
. You can get the visited property for any chunk in a field, but it ismeaningless unless the chunk's textStyle includes "link".

The imageSource, linkText, and visited properties are the only properties thatcan be set to a chunk of a field, but not to
the entire field or any other object. Becausethey are applied to text in fields, they are listed as field properties in the LiveCodeDictionary.

7.5 Creating and Deleting Objects
LiveCode allows you to create and delete objects programmatically. You may optionally
specify all the properties for
a new object before creating it.
to:
To find out whether a custom property set for an object exists, you check whether it's
listed in the object's customPropertySets. The following statement checks whether
an image has a custom property set called "Spanish":

if
"Spanish" is among the lines of the \
customPropertySets of image ID 23945 then...

You can also look in the Custom Properties pane of the object's property inspector, which
lists the custom property sets in
the "Set" menu halfway down the pane.

7.9.5 The default custom property set
An object's default custom
property set is the set that's active if you haven't used the
customPropertySet property to switch to another set. Every object has a defaultcustom property set; you don't need to create it.

If you create
a custom property without first switching to a custom property set – as in
the earlier examples in this topic – the custom property is created in the default set. If you
don't set the customPropertySet property, all your custom properties are created in

the default set.

The default custom property set has no name of its own, and is not listed in the object's
customPropertySets property. To switch from another set to the default set, you set
the object's customPropertySet to empty
:

set the customPropertySet of the target to empty

7.9.6 Using multiple custom property sets
Since only one custom property set can be active at
a time, you can create separatecustom properties with the same name but different values in different sets. Which valueyou get depends on which custom property set is currently active.

A translation example

Suppose your stack uses several custom properties that hold strings in English, to bedisplayed to
the user by various commands. Your stack might contain a statement such asthis:

answer the standardErrorPrompt of this stack

The statement above displays the contents of
the custom property called
"standardErrorPrompt" in a dialog box.

Suppose you decide you want to translate your application into French. To do this, you
make your original set of English custom properties into a custom property set (which
you might call "myEnglishStrings"), and create
a new set called "myFrenchStrings" to
hold the translated properties
.
Changed lines 2335-2372 from:
7.5.1 The Create Object Command
You use
the create command to create a new object.

create [invisible] type [name] [in group]

The type is any control that can be on a card: field, button, image, scrollbar, graphic,
player, or EPS.

The name is the name of the newly created object. If you don't specify a name, the object
is created with a default name.

The group is any group that's on the current card. If you specify a group, the new objectis a member of the group, and exists on each card that has
the group. If you don't specify
a group, the object is created on
the current card and appears only on that card.

create button "Click Me"
create invisible field in first group

For more details, see the create command in
the LiveCode Dictionary. For details on how
to specify the properties of an object before creating it, see the section on Creating
Objects Off-screen Using Template Objects, below.

7.5.2 The Delete Object Command
You can use the delete command
to remove objects from the stack.

delete {object}

The object is any available object.

delete this card
delete button "New Button"

For more details
, see the delete command in the LiveCode Dictionary.

7.5.3 Creating Objects Off-screen Using Template Objects
LiveCode uses template objects to allow you to specify the properties for an object beforeit is created. The template objects are off-screen models – there is one for each possibletype of object, e.g. button, field, graphic, etc.


If you need to create a new object and then set some properties on the object, it is moreefficient to make the changes to the template object, then create the object. Because theobject can be created with all of its properties set correctly, there is no need to lock thescreen and update or reposition the object after creating it. For example, the LiveCodedevelopment environment uses the template objects internally to create new objects fromthe main tool palette.
to:
Each set has the same-named properties, but the values in one set are in French and theother in English. You switch between the sets depending on what language the user
chooses. The statement:

answer the standardErrorPrompt of this stack

provides either the English or French, depending on which custom property set is active:
"myEnglishStrings" or "myFrenchStrings".

7.9.7 Copying custom properties between property sets
When it's created, a custom property set is empty, that is, there aren't any customproperties in it. You put custom properties into a new custom property set by creating thecustom properties while
the set is active:

-- create new set and make it active:
set
the customPropertySet of button 1 to "MyNewSet"
-- now create a new custom property in the current set:
set the myCustomProp of button 1 to true

You can also use
the customProperties property (which was discussed earlier in
this topic) to copy custom properties between sets. For example, suppose you havecreated a full set of custom properties in a custom property set called
"myEnglishStrings", and you want
to copy them to a new custom property set,
"frenchStrings", so you can translate them easily. The following statements create thenew custom property set
, then copy all the properties from the old set to the new one:

-- create the new set:
set the customPropertySet of this stack to "frenchStrings"
-- copy the properties in the English set to the new set:
set the customProperties["frenchStrings "] of this \


 stack to the customProperties["frenchStrings "] \

 of this stack


Caution: Custom property sets in the development environment
The LiveCode development environment uses custom properties to create much of its
own user interface. All these properties are stored in custom property sets whose names
start
with "cRev".
If you're creating custom properties
, but not organizing them into your own custom
property sets, you don't need to worry about LiveCode's custom properties. Unless youchange an object's customPropertySet, your handlers will never interact withthem.
Changed lines 2373-2409 from:
You set properties on template objects in the same way you set properties on normalobjects.

set the {property}
of the template{Objecttype} to {value}

For example,
to create a button with the name "Hello World", positioned at 100,100:

set the name of the templateButton to "Hello World"
set the location of the templateButton to 100,100create button

When you have used the templateObject to create a new object, you should reset it beforeusing it again. Resetting the templateObject sets all off its properties back to defaults.

reset the template[Objecttype]

For example, to reset the templateButton:
reset the templateButton

For more details on the template objects, search the LiveCode Dictionary for "template".

7.6 Property Arrays using the Properties Property
In addition to retrieving individual object properties, you can retrieve or
set an entire setas an array using the properties property. You can use this to edit, copy, export or
import properties.

set the properties of object to propertiesArrayput
the properties of object into propertiesArray

The properties of an object is an array containing that object's significant built-in
properties.

put
the properties of button 1 into myArrayset the properties of last player to the properties \

of player
"Example"

Tip: This example handler shows you how to write the properties of an object to a text
file.
Tip: on mouseUpput the properties of button 1 into tPropertiesArray
combine tPropertiesArray using return and
"|"
ask file "Save properties as:"
if it is not empty then put tPropertiesArray into \
to:
However, if you are using custom property sets--for example, if you have a repeatloop that goes through all of an object's custom property sets--be sure to skip any whose
names start with
"cRev". This ensures that you won't accidentally interfere with any ofLiveCode's reserved custom properties.
7.9.8 Arrays, custom properties, and custom property sets
All the custom properties in a custom property set form an array. The array's name is thecustom property set name, and the elements of the array are the individual customproperties in that custom property set.

Referring to custom properties using array notation

You can use array notation to refer to custom properties in any custom property set. Thislets you get and set any custom property, even if it's not in the current
set, without
changing the current set.

For example, suppose a button has a custom property named "myProp" which is in acustom property set called "mySet". If "mySet" is
the current set, you can refer to the"myProp" property like this:

get the myProp of button 1set the myProp of
the target to 20

But you can also use array notation
to refer to the "myProp" property, even if "mySet" isnot the current set. To refer to this custom property regardless of which custom property
set is active, use statements like the following:

get the mySet["myProp"] of button 1set the mySet[
"myProp"] of the target to 20

Note: Because the default custom property set has no name, you cannot use array
notation to refer to a custom property in the default set.
Storing an array in a custom property set

If you store a set of custom properties in a custom property set, the set can be used justlike an array. You can think of the custom property set as though it were a single customproperty, and the properties in the set as the individual elements of the array.

To store an array variable as a custom property set, use a statement like the following:

set the customProperties["myProperty"] of me to theArray

Changed lines 2403-2434 from:
URL ("file:" & it)
end mouseUp
Tip: In this example, each property name will be written followed by the "|" character
and
the property value and then a return character.
For more details
, see the properties property in the LiveCode Dictionary.

7.7 Property Profiles
A property profile is a collection of object property settings, which is stored as
a set. Aprofile for an object can contain settings for almost any properties of the object.

You can include values for most built-in properties in a profile
, and create as many
different property profiles as you need for any object. Once you've created a profile, you
can switch the object to
the profile to change all the property values that are defined in
the profile.

For example, suppose you create a property profile for a field that includes settings for

the field's color properties. When you switch to that profile, the field's colors change,
while all other properties (not included in the profile) remain the same.

Use property profiles when you want to:
Create "skins" for your applicationDisplay your application in different languagesPresent different levels--"novice","expert", and so onUse different user-interface standards for different platforms

For details on how to create property profiles using the IDE, see
the section on Property
Profiles in
the chapter Building a User Interface.

7.7.1 Profile names
Profile names follow the same rules as variable names. A profile name must be a singleword, consisting of letters, digits, and underscores, and must start with either a letter or

an underscore.
Tip: If you want
to use a single command to switch several objects to a particular profile,
give the profile
the same name for each of the objects it applies to.
7.7.2 The master profile
Every object has
a master profile that holds the default settings for all its properties. Ifyou don't set an object's profile, the master profile is used. When you create a newprofile, you can change settings for various properties to make them different from themaster profile's settings.
to:
The statement above creates a custom property set called "myProperty", and stores each
element in "theArray" as a custom property in
the new set. To retrieve a single element ofthe array, use a statement like this:

get
the myProperty["myElement"] of field "Example"

7.9.9 Deleting a custom property set
As described above, the customPropertySets property of an object is
a list of the
object's custom property sets. You can set the customPropertySets of an object to
control which custom property sets it has.

In LiveCode
, there is no command to delete a custom property set. Instead, you place all
the custom property set names in a variable, delete
the one you don't want from thatvariable, and set the customPropertySets back to the modified contents of the
variable. This removes the custom property set whose name you deleted.


For example, the following statements delete a custom property set called "mySet" fromthe button "My Button":

get the customPropertySets of button "My Button"
set
the wholeMatches to true
delete line lineOffset("mySet",it) of itset the customPropertySets of button "My Button" to it

You can also delete a custom property set in the Custom Properties pane of the object's
property inspector. Select the set's name from
the Set menu, then click the Delete button
to remove it
.

7.10Attaching Handlers to Custom Properties

When you change a custom property, LiveCode sends a setProp trigger to the object
whose property is being changed. You can write a setProp handler to trap this trigger

and respond to the attempt to change the property. Like a message, this trigger uses themessage path, so you can place the setProp handler anywhere in the object's message
path.

Similarly, when you get the value of
a custom property, LiveCode sends a getProp call
to the object whose property is being queried. You can write a getProp handler to reply
to the request for information. Like a function call, the getProp call also traverses the
message path.

Using getProp and setProp handlers, you can:

*
validate a custom property's value before setting it
*
report a custom property's value in a format other than what it's stored as
*
ensure the integrity of a collection of properties by setting them all at once
*
change an object's behavior when a custom property is changed
Changed lines 2450-2496 from:
If you don't specify a property setting in a profile, the master profile's setting is used, so
you don't have
to specify all properties of an object when you create a profile--only theones you want to change.

By default, the master profile is named "Master". You can change the master profile's
name in the Property Profiles pane of the Preferences window.

7
.7.3 Switching between profiles
Switching
a single object

To switch an
object's profile, you can use either the object's property inspector or the
revProfile property.

set the revProfile of player "My Player" to "MyProfile"

Switching all the objects on a card

To switch
the profiles of all the objects on a card, use the revSetCardProfile
command:

revSetCardProfile "MyProfile","My Stack"

The statement above sets the profile of all objects on
the current card of the stack named
"My Stack". (Although the revSetCardProfile command changes a card, you
specify a stack name, not a card name
.)

If an object on the card does not have a profile with the specified name, the object is leftuntouched.

Switching all the objects in a stack

To switch the profiles of all the objects in a stack, use
the revSetStackProfile
command:

revSetStackProfile "MyProfile","My Stack"

The statement above sets
the profile of all objects in the stack named "My Stack".

If an object in the stack does not have a profile with the specified name, the object is leftuntouched.

Switching all the objects in a stack file

To switch
the profiles of all the objects in every stack in a stack file, use therevSetStackFileProfile command:

revSetStackFileProfile "MyProfile","My Stack"

The statement above sets the profile of all objects in the stack named "My Stack", along
with any other stacks in the same stack file.

to:
Note: setProp triggers and getProp calls are not sent when a built-in property is
changed or accessed. They apply only
to custom properties.
7.10.1 Responding to changing a custom property
When you use the set command
to change a custom property, LiveCode sends a
setProp trigger to the object whose property is being changed.

A setProp trigger acts very much like a message does
. It is sent to a particular object.
If that
object's script contains a setProp handler for the property, the handler isexecuted; otherwise, the trigger travels along the message path until it finds a handler for
the property. If it reaches
the end of the message path without being trapped, thesetProp trigger sets the custom property to its new value. For more information aboutthe message path, see the section on the Message Path.

You can include as many setProp handlers in a script for as many different custom
properties as you need
.

7.10.2 The structure of a setProp handler
Unlike
a message handler, a setProp handler begins with the word setProp instead of
the word on. This is followed by the handler's name (which is the same as
the name ofthe custom property) and a parameter that holds the property's new value. A setProp
handler, like all handlers, ends with the word "end" followed by the handler's name.

The following example shows a setProp handler for a custom property named
"percentUsed", and can be placed in
the script of the object whose custom property it is:

setProp percentUsed newAmount

-- responds to setting the percentUsed property

 if newAmount is not a number \

 or newAmount < zero or newAmount > 100 then

 beep 2

exit percentUsed

end if

 pass percentUsedend percentUsed

When you set the "percentUsed" custom property, the "percentUsed" handler is executed:

set the percentUsed of scrollbar "Progress" to 90

When this statement is executed, LiveCode sends a setProp trigger to the scrollbar.
The new value of 90 is placed in the newAmount parameter. The handler makes sure thatthe new value is in the range 0–100; if not, it beeps and exits the handler, preventing theproperty from being set
.
Changed lines 2495-2531 from:
If an object in any of the stacks does not have a profile with the specified name, theobject is left untouched.

7.7.4 Creating a profile
in a handler
In addition to creating property profiles in
the property inspector, you can create a profilein a handler.

To enable creating profiles, check the "Create profiles automatically" box in
the"Property Profiles" pane of the Preferences window. If this box is checked, setting therevProfile property of an object automatically creates the profile.

This ability is particularly useful if you want to create a number of profiles, as shown in
the following example:


on mouseUp

-- creates a profile for each card in
the stack

 repeat with thisCard = 1
to the number of cards

set
the revProfile of card x to "myNewProfile"
end repeatend mouseUp

The handler above creates a profile called "myNewProfile" for all the cards in
the currentstack.

In order for this handler to work,
the "Create profiles automatically" option in the"Property Profiles" pane of the Preferences window must be turned on.

You can control this behavior either in Preferences window or using thegRevProfileReadOnly keyword. If you don't want
to save property changes when
switching profiles, do one of
the following:

Set
the gRevProfileReadOnly variable to true:

global gRevProfileReadOnlyput true into gRevProfileReadOnly

In the "Property Profiles" pane of the Preferences window, uncheck the box labeled
"Don't save changes in profile".

The two methods of changing this setting are equivalent: changing thegRevProfileReadOnly variable also changes
the preference setting, and vice versa.

For more details, see gRevProfileReadOnly in the LiveCode Dictionary.

to:
For more details about the setProp control structure, see setProp in the LiveCode
Dictionary.

Passing
the setProp trigger

When the setProp trigger reaches the engine--the last stop
in the message path--thecustom property is set. If the trigger is trapped and doesn't reach the engine, the customproperty is not set.

To let a trigger pass further along
the message path, use the pass control structure. The
pass control structure stops the current handler and sends the trigger on to the next objectin the message path, just as though the object didn't have a handler for the customproperty.

In the "percentUsed" handler above, if the newAmount is out of range,
the handler uses
the exit control structure
to halt; otherwise, it executes the pass control structure. If the
newAmount is in the right range, the pass control structure lets the property be set.
Otherwise, since
the trigger is not passed, it never reaches the engine, so the property isnot changed.

You can use this capability to check the value of any custom property before allowing itto be set. For example, if a custom property is supposed
to be boolean (true or false), asetProp handler can trap the trigger if the value is anything but true or false:

setProp myBoolean newValue

 if newValue is true or newValue is false

 then pass myBooleanexit myBoolean

Using the message path with a setProp trigger

Because setProp triggers use the message path, a single object can receive
the
setProp triggers for all the objects it owns. For example, setProp triggers for all

controls on a card are sent to the card, if the control's script has no handler for thatproperty. You can take advantage of the message path to implement the same setPropbehavior for objects that all have the same custom property.

Caution: If a setProp handler sets its custom property, for an object that has that
setProphandler in its message path, a runaway recursion will result. To avoid thisproblem, set the lockMessages property to true before setting the custom property.
For example, suppose that all the cards in your stack have a custom property named
"lastChanged". Instead of putting a setProp handler for this property in the script of each
card, you can put a single handler in the stack script:
Changed lines 2530-2573 from:
7.7.5 Adding profile settings in a handler
You can add a property setting to a profile by switching
to the profile, then setting theproperty:

set
the revProfile of button 1 to "MyProfile"
set the foregroundColor of button 1 to "red"
set
the revProfile of button 1 to "Master"

By default, if you change a property and then switch profiles, the property you changed
and its current setting is saved with the profile.

7.8 Custom Properties
A custom property is a property that you create for an object, in addition to its built-in
properties. You can define custom properties for any object, and use them to store any
kind of data.

This topic discusses how to create and use custom properties, and how to organize

custom properties into sets (or arrays). The following section covers how to create virtual
properties and use getProp and setProp handlers to handle custom property
requests.

7
.8.1 Using Custom Properties
A custom property is a property that you define
. You can create as many customproperties for an object as you want, and put any kind of data into them (even binary
data). You can even store a file in a custom property.

Use a custom property when you want to:

*
associate data with a specific object
*
save the data with the object in
the stack file
*
access the data quickly
7.8.2 Creating a Custom Property
You create a custom property by setting the new property
to a value. If you set a customproperty that doesn't exist, LiveCode automatically creates the custom property and sets itto the requested value.

This means that you can create a custom property in a handler or the message box, simply
by using the set command. The following statement creates a custom property called
"endingTime" for a button:

set the endingTime of button "Session" to the long time

You can create custom properties for any object. However, you cannot create globalcustom properties, or custom properties for a chunk of text in a field. Unlike some builtin
properties, a custom property applies only to an object.

to:
setProp lastChanged newDateconvert newDate to seconds
lock messages -- prevent recursionset the lastChanged of the target
to newDateunlock messagesend lastChanged
Note: To refer to
the object whose property is being set, use the target function. The
target refers
to the object that first received the setProp trigger--the object whose
custom property is being set--even if the handler being executed is in the script of another
object.
Setting properties within a setProp handler

In the "lastChanged" example in the box above, the handler sets the custom property
directly, instead of simply passing the setProp trigger. You must use this method if thehandler makes a change to the property's value, because the pass control structure
simply passes on the original value of the property.


Important: If you use the setcommand within a setProphandler to set the same
custom property for the current object, no setProptrigger is sent to the target object
.
(This is to avoid runaway recursion, where the setProp handler triggers itself
.) Setting
a different custom property sends a setProp trigger. So does setting the handler's
custom property for an object other than the one whose script contains the setProphandler.
Using this method, you can not only check the value of a property, and allow it to be setonly if it's in range, you can also change
the value so that it is in the correct range, has thecorrect format, and so on.

The following example is similar
to the "percentUsed" handler above, but instead ofbeeping if the newAmount is out of range, it forces the new value into the range 0–100:

setProp percentUsed newAmount
set the percentUsed of the target to \
max(zero
,min(100,newAmount))
end percentUsed


Nonexistent properties

Changed lines 2559-2586 from:
Important: Each object can have its own custom properties, and custom properties arenot shared between objects. Creating a custom property for one object does not create it
for other objects.
7.8.3 The Content of a Custom Property
You set the value of
a custom property by using its property name together with the set
command, in the same way you
set built-in properties:

set the myCustomProperty of button 1 to false

You can see and change all of an object's custom properties in the Custom Properties
pane of the object's property inspector: click the custom property you want to change,
then enter the new value.

Changing
a part of a property

Like built-in properties
, custom properties are not containers, so you cannot use a chunk
expression to change a part of the
custom property. Instead, you put the property's valueinto a variable and change the variable, then set the custom property back to the newvariable contents:

put
the lastCall of this card into myVarput "March" into word 3 of myVarset the lastCall of thisCard to myVar

7.8.4 Custom Property Names
The name of a custom property must consist
of a single word and may contain any
combination of letters, digits, and underscores (_). The first character must be either aletter or an underscore.

Avoid giving a custom property the same name as a variable. If you refer to a customproperty in a handler, and
there is a variable by the same name, LiveCode uses thecontents of the variable as the name of the custom property. This usually causesunexpected results.

Important: It is important to avoid giving custom properties
the same name as existingengine properties unless those properties are only ever accessed in the context of a
custom property set. Unintended effects may result if you attempt to use the name of an
engine property as a custom property.
to:
If the custom property specified by a setProp handler doesn't exist, the setProp handler isstill executed when a handler sets the property. If the handler passes the setProptrigger, the custom property is created.

Custom property sets and setProp handlers

A setProp handler for
a custom property set behaves differently from a setProp handler
for a custom property that's in the default
set.

When you
set a custom property in a custom property set, the setProp trigger is named
for the set, not the property. The property name is passed in a parameter using a specialnotation. This means that, for custom properties in a set, you write
a single setProp
handler for the set
, rather than one for each individual property.

The following example handles setProp triggers for all custom properties in a
custom
property set called myFrenchStrings, which contains custom properties named
standardErrorPrompt, filePrompt, and perhaps other custom properties:

setProp myFrenchStrings[myPropertyName] newValue-- The myPropertyName parameter contains
the name of-- the property that's being setswitch myPropertyName
case "standardErrorPrompt"

 set
the myFrenchStrings["standardErrorPrompt"] \

of the target to return & newValue & return
exit myFrenchStrings
break


 case "filePrompt"
set the myFrenchStrings["filePrompt"] \


of the target to return& newValue & return
exit myFrenchStrings
break


 default
pass myFrenchStringsend switch
end myFrenchStrings

As you can see from the exit, pass, and end control structures, the name of thissetProp handler is the same as the name of the custom property set that it controls-"
myFrenchStrings". Because
there is only one handler for all the custom properties in thisset, the handler uses the switch control structure to perform a different action for each
property that it deals with.

Suppose you change
the "standardErrorPrompt" custom property:

set the customPropertySet of this stack to \
"myFrenchStrings"
set the standardErrorPrompt of this stack to field 1

Changed lines 2608-2642 from:
Important: Custom property names beginning with "rev" are reserved for LiveCode's
own custom properties. Naming a custom
property with a reserved name may produceunexpected results when working in the development environment.
7.8.5 Referring to Custom Properties
Custom property references look just like built-
in property references: the word the, the
property name
, the word of, and a reference to the object.

For example, to use a custom property called "lastCall" that belongs to a card, use a
statement like
the following:

put the lastCall of
this card into field "Date"

Like built-in properties, custom properties are sources of value, so you can get the valueof a custom property by using it in an expression. The property's value is substituted for
the property reference when the statement is executed. For example
, if the card's"lastCall" custom property is "Today", the example statement above puts the string
"Today" into the "Date" field.


7.8.6 Nonexistent Custom Properties
Custom properties that don't exist evaluate
to empty. For example, if the current card
doesn't have a custom property called "astCall", the following statement empties thefield:

put the lastCall of this card into field "Date" – empty

Note: Referring to a nonexistent
custom property does not cause a script error. This
means that if you misspell a custom property name in a handler, you won't get an error
message, so you might not notice the problem right away.
7.8.7 Finding out Whether
a Custom Property Exists
The customKeys
property of an object lists the object's custom properties, one per line:

put the customKeys of button 1 into field "Custom Props"

To find out whether a custom property for an object exists, you check whether it's listed
in
the object's customKeys. The following statement checks whether a player has acustom property called "doTellAll":

if "doTellAll" is among the lines of
the customKeys \
of player "My Player" then...

to:
LiveCode sends a setProp trigger to the stack, which causes the above handler to
execute. The
property you set – "standardErrorPrompt" – is placed in the"myPropertyName" parameter, and the new value--the contents of field 1 – is placed in
the "newValue" parameter. The handler executes
the case for "standardErrorPrompt",
putting a return character before and after
the property before setting it.

If you set a custom property other than "standardErrorPrompt" or "filePrompt" in the"myFrenchStrings" set,
the default case is executed. In this case, the pass control
structure lets the setProp trigger proceed along the message path, and when it reachesthe engine, LiveCode sets the custom property.

Note: As mentioned above, you can address a custom property in a set either by firstswitching to that set
, or using array notation to specify both set and property. The
following example:
set the customPropertySet of me to "mySet"
set the myProperty of me to true
is equivalent
to:
set the mySet["myProperty"] of me to true

Regardless of how you set the custom property, if it is a member of a custom property
set, the setProp trigger has the name of the set--not the
custom property itself--and you
must use
a setProp handler in the form described above to trap the setProp trigger.

7.10.3 Responding to a request for the value of a custom property
When you use a custom property in an expression, LiveCode sends
a getProp call to theobject whose property's value is being requested.

A getProp call acts very much like a custom function call. It is sent to a particular object.
If that object's script contains a getProp handler for the property, the handler isexecuted, and LiveCode substitutes
the value it returns for the custom property reference.
Otherwise, the call travels along the message path until it finds a handler for
the property.
If the getProp call reaches the end of the message path without being trapped, LiveCodesubstitutes the custom property's value in the expression.

You can include as many getProp handlers in a script as you need.

The structure of a getProp handler

Unlike a message handler, a getProp handler begins with the word getProp instead of
the word on. This is followed by the handler's name (which is the same as the name ofthe custom property). A getProp handler, like all handlers, ends with the word "end"
followed by the handler's name
.
Changed lines 2643-2684 from:
You can also look in the Custom Properties pane of the object's property inspector, which
lists
the custom properties. See the chapter on Building a User Interface for more details.

7.8.8 Custom Properties & Converting Text Between Platforms
When you move a stack developed on a Mac OS or OS X system to a Windows or Unix
system (or vice versa), LiveCode automatically translates text in fields and scripts into

the appropriate character set. However, text in custom properties is not converted
between the ISO and Macintosh character sets
. This is because custom properties can
contain binary data as well as text, and converting them would garble the data.

Characters whose ASCII value is between 128 and 255, such as curved quotes and
accented characters, do not have the same ASCII
value in the Mac OS character set and
the ISO 8859-1 character set used on Unix and Windows systems. If such a character isin a field, it is automatically translated, but it's not translated if it's in a custom property.

Because of this
, if your stack displays custom properties to the user--for example, if thestack puts a custom property into a field--and if the text contains special characters, itmay be displayed incorrectly if you move the stack between platforms. To avoid thisproblem, use one of these methods:

Before displaying the custom property, convert it to the appropriate character set using

the macToISOor ISOToMac function. The following example shows how to convert acustom property that was created on a Mac OS system, when the property is displayed on
a Unix or Windows system:

if the platform is "MacOS" then

 answer the myPrompt of button 1else

 answer macToISO(the myPrompt of button 1)
end if

Instead of storing the custom property as text, store it as HTML
, using the HTMLText
property of fields:

set the myProp
of this card to the HTMLText of field 1

Because the HTMLText property encodes special characters as entities, it ensures thatthe custom property does not contain any special characters--only the platformindependent
encodings for them. You can then set a field's HTMLText to the contents of
the custom property to display it:

set the HTMLText of field "Display" \
to the myProp of this card

7.8.9 Storing a file in a custom property
You can use a URL to store a file's content in a custom property:

to:
The following example is a getProp handler for a custom property named "percentUsed":

getProp percentUsed

global lastAccessTime

put
the seconds into lastAccessTime

pass percentUsedend lastChanged

When you use the "percentUsed" custom property in an expression, the handler isexecuted:

put the percentUsed of card 1 into myVariable

When this statement is executed, LiveCode sends a getProp call to the card to retrieve thevalue of the "percentUsed" property. This executes the getProp handler for
the property.
The example handler stores the current date and time in a global variable before theproperty is evaluated
. For more details, see getProp in the LiveCode Dictionary.

Returning a value from a getProp handler

When the getProp trigger reaches the engine – the last stop in the message path –
LiveCode gets the custom property from the object and substitutes its
value in theexpression where the property was used.

To let a trigger pass further along the message path, use the pass control structure. The
pass control structure stops the current handler and sends the trigger on to the nextobject in the message path
, just as though the object didn't have a handler for the customproperty.

To report
a value other than the value that's stored in the custom property--for example, ifyou want to reformat the value first – you use the return control structure instead of
passing the getProp call. The following example is a getProp handler for a customproperty named "lastChanged", which holds a date in seconds:

getProp lastChanged

get the lastChanged of the target

convert it to long date

return it
end lastChanged

The return control structure, when used in a getProp handler, reports a property valueto the handler that requested it. In the above example, the converted date – not the rawproperty – is what is reported. As you can see from the example
, you're not limited to
returning the actual, stored value
of the custom property. In fact, you can return any valueat all from a getProp handler.
Changed lines 2684-2723 from:
set the myStoredFile of stack "My Stack" \
to URL "binfile:mypicture.jpg"

You restore the file by putting the custom property's value into a URL:

put the myStoredFile of stack "My Stack" \
into URL "binfile:mypicture.jpg"

Because a custom property can hold any kind of data, you can store either text files or
binary files in a
custom property. You can use this capability to bundle media files or
other files in your stack.

Many Mac OS Classic files have a resource fork. To store and restore such a file, you can
use the resfile URL scheme to store the content of the resource fork separately.

Tip: To save space, compress the file before storing it:
Tip: set
the myStoredFile of stack "My Stack" \
to compress(URL "binfile:mypicture.jpg")
Tip: When restoring the file
, decompress it first:
Tip: put decompress(
the myStoredFile of stack "My Stack") \
into URL "binfile:mypicture.jpg"
For more information about using URL containers, see the chapter on Working with
Files
, URLs and Sockets.

7.8.10 Deleting a custom property
As described above, the customKeys property of an object is a list of
the object's
custom properties. You can set the customKeys of an object to control which custom
properties it has.

In LiveCode, there is no command to delete a custom property. Instead, you place all thecustom
property names in a variable, delete the one you don't want from that variable,
and set the object's customKeys back to the modified contents of
the variable. This
removes the custom property whose name you deleted.

For example, the following statements delete a custom property called
"propertyToRemove" from the button "My Button":

get
the customKeys of button "My Button"
set the wholeMatches to true
delete line lineOffset("propertyToRemove",it) of it

to:
Important: If you use a custom property's value within the property's getProp handler,
no getProp call is sent to the target object. This is to avoid runaway recursion, where thegetProp handler calls itself.

A handler can either use the return control structure to return a value, or use the passcontrol structure to let LiveCode get the custom property from the object.

If the getProp call is trapped before it reaches the engine and no value is returned in thegetProp handler, the custom property reports a value of empty. In other words, a getProp
handler must include either a return control structure or a pass control structure, or
its custom property will always be reported as empty.

Using
the message path with a getProp call

Because getProp calls use the message path
, a single object can receive the getProp callsfor all the objects it owns. For example, getProp calls for all controls on a card are sent to
the card
, if the control's script has no handler for that property. You can take advantage ofthe message path to implement the same getProp behavior for objects that all have the
same custom property.

Caution: If a getProphandler is not attached to the object that has the customproperty and it uses the value of the custom
property, a runaway recursion will result. To
avoid this problem, set the lockMessages property to true before getting the custom
property's value.
Nonexistent properties

If
the custom property specified by a getProp handler doesn't exist, the getProp handler isstill executed if the property is used in an expression. Nonexistent properties report
empty; getting
the value of a custom property that doesn't exist does not cause a script
error.

Custom property sets and getProp handlers

A getProp handler for a custom property set behaves differently from a getProp handler
for a custom property that's in the default set.

When you use the value of a custom property in a custom property set, the getProp call isnamed for the set, not the property. The property name is passed in a parameter using
array notation. This means that, for custom properties in a set, you write a single getProp
handler for the set, rather than one for each individual property.

The following example handles getProp calls for all custom properties in a customproperty set called expertSettings, which contains custom properties named
fileMenuContents, editMenuContents, and perhaps other custom properties:

Changed lines 2720-2753 from:
set the customKeys of button "My Button" to it

You can also delete a custom property in
the Custom Properties pane of the object's
Property Inspector. Select the property's name and click
the Delete button to remove it.

7.9 Custom Property Sets
Custom properties can be organized into custom property sets – or arrays of customproperties. A custom property set is a group of custom properties that has a
name you
specify.

When you refer to a custom property, LiveCode looks for that
property in the object's
currently-active custom property set. When you create or set a
custom property,
LiveCode creates it in
the currently-active custom property set, or sets the value of thatproperty in the currently-active set. One custom property set is active at any one time, butyou can use array notation to get or set custom properties in sets other than the currentset.

The examples in
the previous section assume that you haven't created any customproperty sets. If you create a custom property without creating a custom property set for
it, as shown in the previous examples,
the new custom property becomes part of theobject's default custom property set.

7.9.1 Creating custom property sets
To make a custom property set active, you set
the object's customPropertySetproperty to the set you want to use. As with custom properties and local variables, if thecustom property set you specify doesn't exist, LiveCode automatically creates it, so you
can create a custom property set for an object by simply switching to
that set.

The following statement creates a custom property
set called "Alternate" for an object,
and makes it the active set:

set
the customPropertySet of the target to "Alternate"

The statement above creates the custom property set.

You can also view, create, and delete custom property sets in the Custom pane of theobject's property inspector.

You can list all the custom property sets of an object using its customPropertySetsproperty.

As with custom properties, you can create custom property sets for any object. But you
can't create global custom property sets, or custom property sets for a chunk of a field.

to:
getProp expertSettings[thePropertyName]

-- The thePropertyName parameter contains the name of

-- the property that's being set

switch thePropertyName

 case "fileMenuContents"

 if
the expertSettings[fileMenuContents] of the \

target is empty then return "(No items"

else pass expertSettings

break

 case "editMenuContents"

 if
the expertSettings[editMenuContents] of the \

 target is empty then return \

the noviceSettings[editMenuContents] of the target

else pass expertSettingsbreak
default
pass expertSettingsend switch
end expertSettings

As you can see from the pass and end control structures, the
name of this getProp
handler is the same as the name of the custom
property set that it controls –
"expertSettings". Because there is only one handler for all the
custom properties in thisset, the handler uses the switch control structure to perform a different action for each
property that it deals with.

Suppose you get the "fileMenuContents" custom property:

set the customPropertySet of button 1
to "expertSettings"
put the fileMenuContents of button 1 into me

LiveCode sends a getProp call to
the button, which causes the above handler to execute.
The property
you queried – "fileMenuContents" – is placed in the "thePropertyName"
parameter. The handler executes the case for "fileMenuContents": if
the property isempty, it returns "(No items". Otherwise, the pass control structure lets the getProp callproceed along the message path, and when it reaches the engine, LiveCode gets thecustom property.

7.11Virtual Properties

A virtual property is a
custom property that exists only in a setProp and/or getProphandler, and is never actually set. Virtual properties are never attached to the object.
Instead, they act to trigger setPropor getProp handlers
that do the actual work.

When you use the
set command with a virtual property, its setProp handler is executed,
but
the setProp trigger is not passed to the engine, so the property is not attached to theobject. When you use a virtual property in an expression, its getProp handler returns a
Changed lines 2774-2808 from:
7.9.2 Custom property set names
The names of custom property sets should consist of a single word, with any combination
of letters, digits, and underscores (_). The first character should be either
a letter or an
underscore.


It is possible to create a custom property set with a name that has more than one word, or
that otherwise doesn't conform to these guidelines. However, this
is not recommended,
because such a custom property set can't be used with the array notation described below.

Note: When you use the Custom Properties pane in the
property inspector to create a
custom property set,
the pane restricts you to these guidelines.
7.9.3 Referring to custom property sets
To switch the active custom property set, set
the object's customPropertySet property to
the name of the set you want to use:

set the customPropertySet of button 3 to "Spanish"

Any references to
custom property refer to the current custom property set. For example,
suppose you have two custom property sets named "Spanish" and "French", and theFrench
set includes a custom property called "Paris" while the Spanish set does not. Ifyou switch to the Spanish set, the customKeys of the object does not include "Paris",
because the current custom property set doesn't include that
property.

If you refer to a custom property that isn't in the current set, the reference evaluates to

empty. If you set a custom property that isn't in the current set, the custom property iscreated in the set. You can have two custom properties with the same name in differentcustom property sets, and they don't affect each other: changing one does not change theother.

The customProperties property of an object includes only
the custom propertiesthat are in the current custom property set. To specify the customProperties of a
particular custom property set, you include the set's name in square brackets:

put
the customProperties[mySet] of this card into myArray

7.9.4 Finding out whether a custom property set exists
The customPropertySets property
of an object lists the object's custom property
sets, one per line:


answer the customPropertySets of field "My Field"

to:
value without referring to the object. In both cases, using the property simply executes ahandler.

You can use virtual properties to:

*
Give an object a set of behaviors
*
Compute
a value for an object
*
Implement a new property that acts like a built-in property
7.11.1 When to use virtual properties
Because they're not stored with the object, virtual properties are transient: that
is, they arere-computed every time you request them. When a custom property depends on other
properties that may be set independently, it's appropriate to use a virtual
property.

For example, the following handler computes
the current position of a scrollbar as apercentage (instead of an absolute number):

getProp asPercentage -- of a scrollbar
put
the endValue of the target \

-
the startValue of the target into valueExtent
return the thumbPosition of me * 100 div valueExtent

end asPercentage

The "asPercentage"
custom property depends on the scrollbar's thumbPosition,
which can be changed at any time (either by the user or by a handler). Because of this, ifwe
set a custom property for the object, it would have to be re-computed every time thescrollbar is updated in order to stay current. By using a virtual property, you can ensurethat the value of the property is never out of date, because the getProp handler recomputes
it every time you call for the "asPercentage" of the scrollbar.

Virtual properties are also useful solutions when a property's value is large. Because thevirtual property isn't stored with the object, it doesn't take up disk space, and only takesup memory when it
's computed.

Another reason to use a virtual property is to avoid redundancy. The following handler
sets
the width of an object, not in pixels, but as a percentage of the object's owner's
width:


setProp percentWidth newPercentage

set the width of the target to \
the width of
the owner of the target \

* newPercentage div 100end percentWidth
Suppose this handler is placed in the script
of a card button in a 320-pixel-wide stack. Ifyou set the button's "percentWidth" to 25, the button's width is set to 80, which is 25%
of the card's 320-pixel width. It doesn't make much sense to store an object's
percentWidth, however, because it's based on the object's width and its owner's width.

Changed lines 2817-2858 from:
To find out whether a custom property set for an object exists, you check whether it's
listed in the object's customPropertySets. The following statement checks whether
an image has a custom property set called "Spanish":

if "Spanish" is among the lines of the \
customPropertySets of image ID 23945 then...

You can also look in the Custom Properties pane of the object's
property inspector, which
lists the custom property sets in the "Set" menu halfway down the pane.

7.9.5 The default custom property set
An object's default
custom property set is the set that's active if you haven't used the
customPropertySet property to switch
to another set. Every object has a defaultcustom property set; you don't need to create it.

If
you create a custom property without first switching to a custom property set – as in
the earlier examples in this topic – the custom property is created in the default set. If you
don't set the customPropertySet
property, all your custom properties are created in
the default set.

The default custom property
set has no name of its own, and is not listed in the object's
customPropertySets property. To switch from another set to
the default set, you set
the object's customPropertySet to empty:

set the customPropertySet of the target to empty

7.9.6 Using multiple custom property sets
Since only one custom property set can be active at
a time, you can create separatecustom properties with the same name but different values in different sets. Which valueyou get depends on which custom property set is currently active.

A translation example

Suppose your stack uses several custom properties that hold strings in English, to bedisplayed to
the user by various commands. Your stack might contain a statement such asthis:

answer the standardErrorPrompt of this stack

The statement above displays the contents of the custom
property called
"standardErrorPrompt" in a dialog box.

Suppose you decide you want to translate your application into French. To do this, you
make your original set of English custom properties into a custom property set (which

you might call "myEnglishStrings"), and create a new set called "myFrenchStrings" to
hold the translated properties.

to:
Consider using virtual properties whenever you want to define an attribute of an object,
but
it doesn't make sense to store the attribute with the object – because it would beredundant, because possible changes to the object mean it would have to be re-computed
anyway, or because the property is too large to be easily stored.

7.11.2 Handlers for a virtual
property
As you can see by looking at the example above, a handler for a virtual property isstructured like a handler for any other custom property. The only structural difference isthat, since the handler has already done everything necessary, there's no need to actually
attach the custom property to the object or get its value from the object
. When you set avirtual property or use its value, the setProp trigger or getProp call does not reach
the engine, but is trapped by a handler first.

Virtual property setProp handlers

A setProp handler for an ordinary custom
property includes the pass control structure,
allowing the setProp trigger to reach the engine and
set the custom property (or else it
includes a set command that sets
the property directly). A handler for a virtual property,
on
the other hand, does not include the pass control structure, because a virtual property
should not be set. Since the property is set automatically when the trigger reaches the end
of the message path,
a virtual property's handler does not pass the trigger.

If you examine an object's custom properties after setting a virtual property, you'll find
that the custom property hasn't actually been created. This happens because thesetProp handler traps the call to set the property; unless you pass
the setProp trigger,
the property isn't passed to LiveCode, and the property isn't set.

Virtual property getProp handlers

Similarly, a getProp handler for an ordinary custom property either gets the
property'svalue directly, or passes the getProp call so that the engine can return the property'svalue. But in the case of a virtual property, the object doesn't include the property, so thegetProp handler must return a value.

7.11.3 Creating new object properties
You can use virtual properties to create a new property that applies to all objects, or to allobjects of a particular type. Such a property acts like a built-in property, because you can
use it for any object. And because a virtual property doesn't rely on a custom property
being stored in the object, you don't need to prepare by creating the property for each newobject you create: the virtual property is computed only when you use it in an expression.

The following example describes how to implement a virtual property called
"percentWidth" that behaves like a built-in property.

Setting the "percentWidth" property

Suppose you place the "percentWidth" handler described above in a stack script instead
of in a button's script:

Changed lines 2857-2893 from:
Each set has the same-named properties, but the values in one set are in French and theother in English. You switch between the sets depending on what language the user
chooses. The statement:

answer
the standardErrorPrompt of this stack

provides either
the English or French, depending on which custom property set is active:
"myEnglishStrings" or "myFrenchStrings".

7
.9.7 Copying custom properties between property sets
When it's created, a custom property
set is empty, that is, there aren't any customproperties in it. You put custom properties into a new custom property set by creating thecustom properties while the set is active:

-- create new set and make it active:
set the customPropertySet of button 1 to "MyNewSet"
-- now create a new custom property in
the current set:
set
the myCustomProp of button 1 to true

You can also use the customProperties property (which was discussed earlier in

this topic) to copy custom properties between sets. For example, suppose you havecreated a full set of custom properties in a custom property set called
"myEnglishStrings", and you want to copy them to a new custom property set,
"frenchStrings", so you can translate them easily. The following statements create thenew custom property set
, then copy all the properties from the old set to the new one:

-- create the new set:
set the customPropertySet of this
stack to "frenchStrings"
-- copy the properties in
the English set to the new set:
set
the customProperties["frenchStrings "] of this \


 stack to
the customProperties["frenchStrings "] \

 of this stack

Caution: Custom property sets in
the development environment
The LiveCode development environment uses custom properties to create much of its
own user interface. All these properties are stored
in custom property sets whose names
start with "cRev".
If you're creating custom properties, but not organizing them into your own custom
property sets, you
don't need to worry about LiveCode's custom properties. Unless youchange an object's customPropertySet, your handlers will never interact withthem.
to:
setProp percentWidth newPercentage
set
the width of the target to \
the width of the owner of the target \

* newPercentage div 100end percentWidth
Because setProp triggers use
the message path, if you set the "percentWidth" of any
object in
the stack, the stack receives the setProp trigger (unless it's trapped by another
object first). This means that if the handler is in the stack's script, you can set the"percentWidth" property of any object in the stack.

If you place the handler in
a backscript, you can set the "percentWidth" of any object,
anywhere in the application.


Note: To refer to the object whose property is being set, use the target function. The
target refers to the object that first received
the setProp trigger--the object whose
custom property is being set--even if the handler being executed is in the script of another

object.
Getting the "percentWidth" property

The matching getProp handler, which lets
you retrieve the "percentWidth" of an object,
looks like this:

getProp percentWidth
return 100 * (the width of the target \
div the width of the owner of the target)
end percentWidth

If you place the handler above in a card button's script
, the following statement reportsthe button's width as a percentage:

put
the percentWidth of button "My Button" into field 12

For example, if the
stack is 320 pixels wide and the button is 50 pixels wide, the button'swidth is 15% of the card width, and the statement puts "15" into the field.

Like the setProp handler for this property,
the getProp handler should be placed far
along the message path. Putting it in a stack script makes the property available to allobjects
in the stack; putting it in a backscript makes the property available to all objectsin the application.

Limiting the "percentWidth" property

Most built-in properties
don't apply to all object types, and you might also want to createa virtual property that only applies to certain types of objects. For example, it's not very
Changed lines 2897-2925 from:
However, if you are using custom property sets--for example, if you have a repeatloop that goes through all of an object's custom property sets--be sure to skip any whose
names start with "cRev". This ensures that you won't accidentally interfere with any ofLiveCode's reserved custom properties.
7.9.8 Arrays, custom properties, and custom property sets
All the custom properties in a custom property set form an array. The array's name is thecustom property
set name, and the elements of the array are the individual customproperties in that custom property set.

Referring to custom properties using array notation

You can use array notation to refer to custom properties in any custom property set. Thislets you get and set any custom property, even if it's not in the current set, without
changing the current set.

For example
, suppose a button has a custom property named "myProp" which is in acustom property set called "mySet". If "mySet" is the current set, you can refer to the"myProp" property like this:

get the myProp of button 1set the myProp
of the target to 20

But you can also use array notation to refer to the "myProp" property, even if "mySet" isnot the current set. To refer to this custom property regardless of which custom property
set is active, use statements like the following:

get the mySet["myProp"] of button 1set the mySet["myProp"] of the target to 20

Note: Because
the default custom property set has no name, you cannot use array
notation
to refer to a custom property in the default set.
Storing an array in a custom property set

If you store a set of custom properties in a custom property set
, the set can be used justlike an array. You can think of the custom property set as though it were a single customproperty, and the properties in the set as the individual elements of the array.

To store an array variable as a custom property set, use a statement like the following:

set the customProperties["myProperty"] of me to theArray

to:
useful to get the width of a substack as a percentage of its main stack, or the width of acard as a percentage of the stack's width.

You can limit the property to certain object types by checking the target object's
name:

setProp percentWidth newPercentage

 if word 1 of the name of the target is "stack" \

 or word 1 of the name of the target is "card" \

then exit setProp

set the width of the target to \

 
the width of the owner of the target \

* newPercentage div 100end percentWidth
The first word of an object's name is the object type, so the above revised handler
ignores setting the "percentWidth" if the object is a card or stack.

7.12Managing Windows, Palettes and Dialogs

LiveCode provides complete control over all aspects of window management
, including
moving, re-layering, and changing window mode.

7.12.1 Moving a window
Usually, you use either the locationor rectangle property of a stack to move the
stack window.

Thelocation property specifies
the center of the stack's window, relative to the top leftcorner of the main screen. Unlike the location of controls, the location of a stack
is specified in absolute coordinates. The following statement moves a stack to the center
of the main screen:

set the location of stack "Wave" to the screenLoc

The rectangle property of a stack specifies the position of all four edges, and can beused to resize
the window as well as move it:

set the rectangle of this stack
to "100,100,600,200"

Tip: To open a window at a particular place without flickering, set the stack's location or
rectangle property to the desired value either before going to it
, or in the stack’s
preOpenStack handler.
Changed lines 2941-2986 from:
The statement above creates a custom property set called "myProperty", and stores each
element in "theArray" as a custom property in the new set. To retrieve a single element ofthe array, use a statement like this:

get the myProperty["myElement"] of field "Example"

7.9.9 Deleting
a custom property set
As described above,
the customPropertySets property of an object is a list of the
object's custom property sets. You can set
the customPropertySets of an object to
control which custom property sets it has.

In LiveCode, there is no command to delete a custom property set. Instead, you place all
the custom property set names in a variable, delete the one you don't want from thatvariable, and set the customPropertySets back to the modified contents of the
variable. This removes the custom property set whose name you deleted.

For example
, the following statements delete a custom property set called "mySet" fromthe button "My Button":

get the customPropertySets of button "My Button"
set the wholeMatches to true
delete line lineOffset("mySet",it) of itset the customPropertySets of button "My Button" to it

You can also delete a custom property set in
the Custom Properties pane of the object's
property inspector. Select the set's name from the Set menu, then click the Delete button
to remove it.

7.10Attaching Handlers to Custom Properties

When you change a custom property, LiveCode sends a setProp trigger to the object
whose property is being changed. You can write a setProp handler to trap this trigger
and respond to the attempt to change the property. Like a message, this trigger uses themessage path, so you can place the setProp handler anywhere in the object's message
path.

Similarly, when you get
the value of a custom property, LiveCode sends a getProp call
to the object whose property is being queried. You can write a getProp handler to reply
to the request for information. Like a function call, the getProp call also traverses the
message path.

Using getProp and setProp handlers
, you can:

*
validate
a custom property's value before setting it
*

report a custom property's value in a format other than what it's stored as
*
ensure the integrity of a collection of properties by setting them all at once
*
change an object's behavior when a custom property is changed
to:
You can also use associated properties to move a window. Changing a stack's bottomor
top property moves the window up or down on the screen. Changing the leftor
right property moves the window from side to side.

7.12.2 Changing a window's layer
You bring
a window to the front by using the go command:

go stack "Alpha"

If the stack is already open, the go command brings it to
the front, without changing its
mode.


To find out the layer order of open stack windows, use the openStacks function. This
function lists all open stack windows in order from front to back.

The palette layer

Normally, palette windows float above editable windows and modeless dialog boxes. Apalette will always above a standard window, even if you bring the standard window to
the front. This helps ensure that palettes
, which usually contain tools that can be used in
any window, cannot disappear behind document windows. It's also a good reason to makesure you design palette windows to be small, because other windows cannot be moved in
front of them if the palette blocks part of
the window.

The system palette layer

System windows--stacks whose systemWindow property is true--float above all other
windows, in every running application. This means that even if the user brings another
application to the front, your application's system windows remain in front of allwindows.

System windows are always in front of other windows, and you cannot change thisbehavior.

7.12.3 The active window
In most applications, commands are applied to the active window. Since LiveCode givesyou the flexibility to use several different window types, not all of which are editable, thecurrent stack is not always
the same as the active window. The current stack is the targetof menu choices such as View -> Go Next and is the stack specified by the expressionthis
stack.

For example, executing the find command may have unexpected results if stacks ofdifferent modes are open, because under these conditions
, the search may target a stack
that is not the frontmost window.


Finding the current stack

Changed lines 2981-3024 from:
Note: setProp triggers and getProp calls are not sent when a built-in property is
changed or accessed. They apply only to custom properties.

7.10.1 Responding to changing a custom property
When you use the set command to change a custom property, LiveCode sends a
setProp trigger to the object whose
property is being changed.

A setProp trigger acts very much like a message does. It
is sent to a particular object.
If that object's script contains a setProp handler for the property, the handler isexecuted; otherwise, the trigger travels along the message path until it finds a handler for
the property. If it reaches the end of
the message path without being trapped, thesetProp trigger sets the custom property to its new value. For more information aboutthe message path, see the section on the Message Path.

You can include as many setProp handlers in a script for as many different custom
properties as you need.

7.10.2 The structure of a setProp handler
Unlike a message handler, a setProp handler begins with the word setProp instead of
the word on. This is followed by the handler's name (which is the same as
the name ofthe custom property) and a parameter that holds the property's new value. A setProp
handler
, like all handlers, ends with the word "end" followed by the handler's name.

The following example shows a setProp handler for a custom property named
"percentUsed", and can be placed in the script of
the object whose custom property it is:

setProp percentUsed newAmount

-- responds
to setting the percentUsed property

 if newAmount
is not a number \

 or newAmount < zero or newAmount > 100 then

 beep 2

exit percentUsed

end if

 pass percentUsedend percentUsed

When you set the "percentUsed" custom property, the "percentUsed" handler is executed:

set the percentUsed of scrollbar "Progress" to 90

When this statement is executed,
LiveCode sends a setProp trigger to the scrollbar.
The new value of 90
is placed in the newAmount parameter. The handler makes sure thatthe new value is in the range 0–100; if not, it beeps and exits the handler, preventing theproperty from being set.
to:
The current stack--the stack that responds to commands--is designated by thedefaultStack property. To determine which stack is the current stack, use the
following rules:

1. If any stacks are opened in an editable window, the current stack is the frontmostunlocked stack. (A stack is unlocked if its cantModify
property is set to false.)
2. If there are no unlocked stacks open, the current stack
is the frontmost locked stack in
an editable window.
3. If there are no stacks open in an editable window
, the current stack is the frontmoststack in a modeless dialog box.
4. If there are no editable or modeless windows open,
the current stack is the frontmostpalette.
Another way of expressing this set of rules is to say that the current stack is
the frontmost
stack with
the lowest mode property. You can find out which stack has the lowest mode
using the topStack function.


The topStack function and the defaultStack property:
The defaultStack property specifies which stack is the current stack. By default, the
defaultStack is set to the topStack, although you can change the
defaultStack to any open stack.



The topStack function goes through
the open stacks first by mode, then by layer. For
example, if any editable windows are open
, the topmost editable window is the
topStack. If there are no editable windows, the topStack is the topmost modeless
dialog box, and so on.


Changing the current stack

To operate on a stack other than
the current stack, set the defaultStack property to
the stack you want
to target before executing the commands. Usually, thedefaultStack is the topStack, but you can change it if you want to override theusual rules about which window is active.

A note about Unix systems

If your system is set up to use pointer focus rather than click-to-type or explicit focus,
you may experience unexpected results when using
LiveCode, since the current stack willchange as you move the mouse pointer. It is recommended that you configure your
system to use explicit focus when using LiveCode or any other applications created in
LiveCode.

7.12.4 Creating a backdrop
For some applications, you may want to create a solid or patterned backdrop behind your
application's windows. This backdrop prevents other applications' windows from being

Changed lines 3023-3056 from:
For more details about the setProp control structure, see setProp in the LiveCode
Dictionary.

Passing the setProp trigger

When the setProp trigger reaches the engine--the last stop in the message path--thecustom property is set. If the trigger is trapped and doesn't reach the engine
, the customproperty is not set.

To let a trigger pass further along
the message path, use the pass control structure. The
pass control structure stops the current handler and sends the trigger on to the next objectin the message path, just as though the object didn't have a handler for the customproperty.

In
the "percentUsed" handler above, if the newAmount is out of range, the handler uses
the exit control structure
to halt; otherwise, it executes the pass control structure. If the
newAmount is in the right range, the pass control structure lets the property
be set.
Otherwise, since the trigger is not passed, it never reaches the engine, so the property isnot changed.

You
can use this capability to check the value of any custom property before allowing itto be set. For example, if a custom property is supposed to be boolean (true or false), asetProp handler can trap the trigger if the value is anything but true or false:

setProp myBoolean newValue

 if newValue is true or newValue is false

 then pass myBooleanexit myBoolean

Using the message path with a setProp trigger

Because setProp triggers use the message path
, a single object can receive the
setProp triggers for all the objects it owns. For example, setProp triggers for all
controls on a card are sent to the card, if the control's script has no handler for thatproperty. You can take advantage of the message path to implement the same setPropbehavior for objects that all have the same custom property.

Caution: If a setProp handler sets its custom property, for an object that has that
setProphandler in its message path, a runaway recursion will result
. To avoid thisproblem, set the lockMessages property to true before setting the custom property.
For example, suppose that all the cards in your stack have a custom property named
"lastChanged". Instead of putting a setProp handler for this property in the script of each
card, you can put a single handler in the stack script:
to:
seen – although it does not close those windows – so it's appropriate for applications likea game or kiosk, where the user doesn't need to see other applications and where you
want to keep distractions to a minimum.

Note: In LiveCode Media edition
, you cannot turn off the backdrop property.
To create a backdrop, you set
the backdrop property to either a valid color reference,
or the ID of an image you want to use as a tiled pattern:

set
the backdrop to "#99FF66" -- a color
set the backdrop to 1943 -- an image ID

In
the LiveCode development environment, you can create a backdrop by choosing View
-> Backdrop. Use the Preferences dialog box
to specify a backdrop color to use.

7
.12.5 Open, Closed, and Hidden Windows
Each open stack is displayed in a stack window. A stack can
be open without being
visible, and can be loaded into memory without being open.

Hidden stacks

A stack window
can be either shown or hidden, depending on the stack's visible
property. This means a window can be open without being visible on the screen.

Tip: To list all open stacks
, whether they're visible or hidden, use the openStacks
function.
Loaded stacks

A stack can also be loaded into memory without actually being open. A stack whosewindow is closed (not just hidden) is not listed by the openStacks function. However,
it takes up memory
, and its objects are accessible to other stacks. For example, if a closed
stack that's loaded into memory contains a certain image, you can use the image as abutton icon in another stack.

A stack can be loaded into memory without being open under any of the following
conditions:

A handler in another stack referred to a property of the closed stack. This automatically
loads the referenced stack into memory.

The stack is in the same stack file as another stack that is open
.
Changed lines 3062-3089 from:
setProp lastChanged newDateconvert newDate to seconds
lock messages -- prevent recursionset the lastChanged of the target to newDateunlock messagesend lastChanged
Note: To refer to the object whose property is being set, use the target function
. The
target refers to the object that first received the setProp trigger--the object whose

custom property is being set--even if the handler being executed is in the script of another
object.

Setting properties within a setProp handler

In the "lastChanged" example in the box above
, the handler sets the custom property
directly, instead of simply passing the setProp trigger. You must use this method if thehandler makes a change to
the property's value, because the pass control structure
simply passes on the original value of the property.

Important: If you use the setcommand within a setProphandler to set
the same
custom property for
the current object, no setProptrigger is sent to the target object.
(This is to avoid runaway recursion, where
the setProp handler triggers itself.) Setting
a different custom property sends a setProp trigger. So does setting the handler's
custom property for an object other than the one whose script contains
the setProphandler.
Using this method, you can not only check the value of a property, and allow it to be setonly if it's in range, you can also change
the value so that it is in the correct range, has thecorrect format, and so on.

The following example is similar to the "percentUsed" handler above, but instead ofbeeping if the newAmount is out of range, it forces the new value into the range 0–100:

setProp percentUsed newAmount
set
the percentUsed of the target to \
max(zero
,min(100,newAmount))
end percentUsed

Nonexistent properties

to:
The stack was opened and then closed, and its destroyStack property is set to false.
(If the destroyStack property is false, the stack is closed, but not unloaded, when its
window is closed
.)

Tip: To list all stacks in memory, whether they're open or closed, use the

revLoadedStacks function.
7.12.6 The states of a stack
A stack, then, can be in any
of four states:

Open and visible:The stack is loaded into memory, its window is open
, and the window
is visible.

Open and hidden:The stack is loaded into memory, its window is open, but the windowis hidden. The stack is listed in
the Window menu and in the Application Browser.

Closed but loaded into memory:The stack is loaded into memory, but its window is not
open and it is not listed by
the openStacks function or in the Window menu.
However, its objects are still available to other stacks, and it is listed in
the Application
Browser. A stack that is closed but loaded into memory has a mode property of zero.

To remove such a stack from memory, choose Tools -> Application Browser, find
the
stack's name, and Control-click it (Mac OS or OS X) or Right-click it (Unix or
Windows) in the Application Browser window and choose "Close and Remove fromMemory" from
the contextual menu.

Closed:The stack
is not loaded into memory and has no effect on other stacks.

7.12.7 Window Types and the Mode Property
In a script
, you can find out a stack window's type by checking the stack's mode
property. This read-only property reports a number that depends on
the window type. Forexample, the mode of an editable window is 1, and the mode of a palette is 4.

You can use the mode property in a script to check what sort of window a stack is being
displayed in:

if the mode of this stack is 5 then -- modal dialog box
close this stack
else -- some other type of windowbeepend if

For complete information about the possible values of the mode property, see its entry in
the LiveCode Dictionary.

Changed lines 3102-3149 from:
If the custom property specified by a setProp handler doesn't exist, the setProp handler isstill executed when a handler sets the property. If the handler passes the setProptrigger, the custom property is created.

Custom property sets and setProp handlers

A setProp handler for a custom property set behaves differently from a setProp handler
for a custom property that
's in the default set.

When you set
a custom property in a custom property set, the setProp trigger is named
for the set, not the property. The property name is passed in a parameter using a specialnotation. This means that,
for custom properties in a set, you write a single setProp
handler for the set, rather than one
for each individual property.

The following example handles setProp triggers for all custom properties in a custom
property set called myFrenchStrings, which contains custom properties named
standardErrorPrompt, filePrompt,
and perhaps other custom properties:

setProp myFrenchStrings[myPropertyName] newValue-- The myPropertyName parameter contains the name of-- the property that's being setswitch myPropertyName

case "standardErrorPrompt"

 set the myFrenchStrings["standardErrorPrompt"] \

of the target to return & newValue & return
exit myFrenchStrings
break


 case "filePrompt"
set the myFrenchStrings["filePrompt"] \


of the target to return& newValue & return
exit myFrenchStrings
break


 default
pass myFrenchStringsend switch
end myFrenchStrings


As you can see from the exit, pass, and end control structures, the name of thissetProp handler is the same as the name of the custom property set that it controls-"
myFrenchStrings". Because there is only one handler for all the custom properties in thisset, the handler uses
the switch control structure to perform a different action for each
property that it deals with.

Suppose you change the "standardErrorPrompt" custom property:

set the customPropertySet of this stack
to \
"myFrenchStrings"
set the standardErrorPrompt of this
stack to field 1
to:
7.12.8 Window Appearance
Details of a window's appearance, such as the height of its title bar and the background
color or pattern in
the window itself, are mainly determined by the stack's mode. Thereare a few additional elements of window appearance that you can control with specificproperties.

The metal property

On OS X systems, you use a stack
's metal property to give the stack window a textured
metal appearance. This metal appearance applies to
the stack's title bar and itsbackground.

Tip: The metal appearance, in general, should be used only for the main window of an
application, and only
for windows that represent a physical media device such as a CD
player. See Apple's Aqua user-interface guidelines
for more information.
Window background color

The background color or pattern of a window's content area--the part that isn't part of thetitle bar--is determined by the window type
and operating system, by default. For
example, on OS X systems, a striped background appears in palettes and modeless dialog
boxes.


If you want a window to have a specific color or pattern, you can set the stack'sbackgroundColoror backgroundPattern property:

set the backgroundColor
of stack "Alpha" to "aliceblue"
set the backgroundPattern of stack "Beta" to 2452 -- img ID


This color or pattern overrides the usual color or background pattern.

7.12.9 The Decorations Property
Most
of the properties that pertain to a window's appearance can also be set in the stack's
decorations property. The decorations of a stack consists of a comma-separated
list of decorations:

set
the decorations of stack "Gamma" to "title,minimize"

The statement above sets the stack'sminimizeBox
property to true, as well as showing
its title bar, and sets other stack properties (maximizeBox, closeBox, metal)
to
false. Conversely, if you set a stack's minimizeBox property to true, its
decorations property is changed to include "minimize" as one of its items. In this
way, the decorations property of a stack interacts with its closeBox,
minimizeBox, zoomBox, metal, shadow, and systemWindow properties.

The decorations property and menu bars in a window

Changed lines 3144-3177 from:
LiveCode sends a setProp trigger to the stack, which causes the above handler to
execute
. The property you set – "standardErrorPrompt" – is placed in the"myPropertyName" parameter, and the new value--the contents of field 1 – is placed in
the "newValue" parameter. The handler executes
the case for "standardErrorPrompt",
putting a return character before and after the property before setting it.

If you set a custom property other than "standardErrorPrompt" or "filePrompt" in
the"myFrenchStrings" set, the default case is executed. In this case, the pass control
structure lets the setProp trigger proceed along the message path, and when it reachesthe engine, LiveCode sets the custom property.

Note: As mentioned above, you can address a custom property in a set either by firstswitching to that set, or using array notation to specify both set and property. The
following example:
set the customPropertySet of me to "mySet"
set the myProperty of me to true
is equivalent to:

set the mySet["myProperty"] of me to true
Regardless of how you set the custom property, if it is a member of a custom property
set,
the setProp trigger has the name of the set--not the custom property itself--and you
must use
a setProp handler in the form described above to trap the setProp trigger.

7.10.3 Responding to a request for the value of a custom
property
When you use a custom property in an expression, LiveCode sends a getProp call to theobject whose property's value is being requested.

A getProp call acts very much like a custom function call. It is sent to a particular object
.
If that object's script contains a getProp handler for the property,
the handler isexecuted, and LiveCode substitutes the value it returns for the custom property reference.
Otherwise, the call travels along the message path until it finds a handler for
the property.
If the getProp call reaches the end of the message path without being trapped, LiveCodesubstitutes the custom property's value in the expression.

You can include as many getProp handlers in a script as you need.

The structure of a getProp handler

Unlike a message handler, a getProp handler begins with
the word getProp instead of
the word on. This is followed by the handler's name (which is the same as the name ofthe custom property). A getProp handler, like all handlers, ends with the word "end"
followed by the handler's name
.
to:
On Unix and Windows systems, the menu bar appears at the top of the window. On thesesystems, whether a window displays its menu bar is determined by whether the stack'sdecorations property includes "menu":

set the decorations
of this stack to "title,menu"

On Mac OS and OS X systems,
the menu bar appears at the top of the screen, outside any
window. On these systems, the "menu" decoration has no effect.

Title bar


The user drags
the title bar of a window to move the window around the screen. In
general, if the title bar is not displayed, the user cannot move the window. You use thedecorations property (discussed below) to hide and show a window's title bar.

When the user drags the window, LiveCode sends a moveStack message to the current
card.

The decorations property affects only whether the window can be moved by
dragging it. Even if a stack's decorations property does not include the title bar

decoration, you can still set a stack's location, rectangle, and related properties to
move or resize the window.

Window title

The title that appears in
the title bar of a window is determined by the stack's label
property. If
you change a stack's label in a script, the window's title is immediately
updated.

If the label is empty, the title bar displays the stack's name
property. (If the stack is in
an editable window whose cantModify is false, an asterisk appears after the windowtitle to indicate this, and if the stack has more than one card, the card number also appearsin the window title. These indicators do not appear if the stack has alabel.)

Because
the window title is determined by the stack's label property instead of its
name
property, you have a great deal of flexibility in changing window title. Your scriptsrefer to the stack by its name--which doesn't need to change--not its label, so you can
change the window title without changing any scripts that refer to the stack.

The close box

The close box allows the user to close the window by clicking it. To hide or show theclose box, you set
the stack's closeBox property:

set
the closeBox of stack "Bravo" to false

When
the user clicks the close box, LiveCode sends a closeStackRequest message,
followed by a closeStack message
, to the current card.
Changed lines 3187-3226 from:
The following example is a getProp handler for a custom property named "percentUsed":

getProp percentUsed

global lastAccessTime

put the seconds into lastAccessTime

pass percentUsedend lastChanged

When you
use the "percentUsed" custom property in an expression, the handler isexecuted:

put
the percentUsed of card 1 into myVariable

When this statement is executed, LiveCode sends a getProp call to the card to retrieve thevalue of the "percentUsed" property. This executes
the getProp handler for the property.
The example handler stores the current date
and time in a global variable before theproperty is evaluated. For more details, see getProp in the LiveCode Dictionary.

Returning a value from a getProp handler

When
the getProp trigger reaches the engine – the last stop in the message path –
LiveCode gets the custom property from the object
and substitutes its value in theexpression where the property was used.

To let a trigger pass further along
the message path, use the pass control structure. The
pass control structure stops the current handler and sends the trigger on to the nextobject in the message path, just as though the object didn't have a handler for the customproperty.

To report a value other than
the value that's stored in the custom property--for example, ifyou want to reformat the value first – you use the return control structure instead of
passing the getProp call. The following example is a getProp handler for a customproperty named "lastChanged", which holds a date in seconds:


getProp lastChanged

get the lastChanged of
the target

convert it to long date

return it
end lastChanged

The return control structure, when used in a getProp handler, reports
a property valueto the handler that requested it. In the above example, the converted date – not the rawproperty – is what is reported. As you can see from the example, you're not limited to
returning the actual, stored value of the custom property. In fact, you can return any valueat all from a getProp handler.

to:
The closeBox property affects only whether the window can be closed by clicking.
Even if a stack's closeBox property is false, you can still use the close command in a
handler or
the message box to close the window.

The minimize box or collapse box

The terminology and behavior of this part of the title bar varies depending on platform.
On Mac OS systems, the collapse box shrinks
the window so only its title bar is shown.
The minimize box (OS X
and Windows systems) or iconify box (Unix systems) shrinksthe window to a desktop icon.

To hide or show the minimize box or collapse box, you set
the stack's minimizeBox
property:

set
the minimizeBox of this stack to true

that appears when the stack is minimized.
Tip: On OS X
and Unix systems, you can set a stack's icon property to specify the icon

When the user clicks
the minimize box or collapse box, LiveCode sends an
iconifyStack message to the current card.

The maximize box or zoom box

The terminology and behavior of this part of
the title bar varies depending on platform.
On Mac OS and OS X systems,
the zoom box switches the window between its currentsize and maximum size. The maximize box (Unix and Windows systems) expands thewindow to its maximum size.

To hide or show the zoom box or maximize box, you set the stack's zoomBox property:

set the zoomBox of stack "Hello" to false

When
the user clicks the zoom box or maximize box, LiveCode sends a resizeStack
message to the current card.

7.12.10 Making
a stack resizable
A stack's resizable property determines whether
the user can change its size by dragging
a corner or edge (depending on operating system) of the stack window.

Tip: To move and resize controls automatically to fit when a stack is resized, use the"Geometry" pane in the control's property inspector.
Changed lines 3226-3260 from:
Important: If you use a custom property's value within the property's getProp handler,
no getProp call is sent to the target object. This is to avoid runaway recursion
, where thegetProp handler calls itself.
A handler can either use the return control structure to return a value, or use the passcontrol structure to let LiveCode get the custom
property from the object.

If the getProp call is trapped before it reaches the engine and no value is returned in thegetProp handler,
the custom property reports a value of empty. In other words, a getProp
handler must include either a return control structure or
a pass control structure, or
its custom property will always be reported as empty.

Using the message path
with a getProp call

Because getProp calls use the message path, a single object can receive the getProp callsfor all the objects it owns. For example, getProp calls for all controls on a card are sent to
the card, if the control's script has no handler for that property. You can take advantage ofthe message path to implement the same getProp behavior for objects that all have the
same custom property.

Caution: If a getProphandler is not attached to the object that has the customproperty and it uses the value of the custom property,
a runaway recursion will result. To
avoid this problem, set the lockMessages property to true before getting the custom
property's value.
Nonexistent properties

If
the custom property specified by a getProp handler doesn't exist, the getProp handler isstill executed if the property is used in an expression. Nonexistent properties report
empty; getting the value of a custom property that doesn't exist does not cause a script
error.

Custom property sets and getProp handlers

A getProp handler
for a custom property set behaves differently from a getProp handler
for a custom property that's in the default set
.

When you use
the value of a custom property in a custom property set, the getProp call isnamed for the set, not the property. The property name is passed in a parameter using
array notation. This means that, for custom properties in a set, you write a single getProp

handler for the set, rather than one for each individual property.

The following example handles getProp calls for all custom properties in a customproperty set
called expertSettings, which contains custom properties named
fileMenuContents, editMenuContents
, and perhaps other custom properties:
to:
Some stack modes cannot be resized, regardless of the setting of the stack's resizable
property. Modal dialog boxes, sheets, and drawers cannot be resized by the user
, and do
not display a resize box.

The resizable property affects only whether the window can be resized by dragging acorner or edge. Even if a stack's resizable
property is set to false, you can still set a
stack's location, rectangle, and related properties to move or resize the window.

When
the user resizes a stack, LiveCode sends a resizeStack message to the current card.

7.12.11 Irregularly-Shaped and Translucent Windows
You can set
a stack’s windowShape property to the transparent, or alpha channel of an
image that has been imported together
with its alpha channel. This allows you to create awindow with "holes" or a window with variable translucency. You can apply a shape to
any type of stack, regardless of the mode it is opened, allowing such a window to exhibitmodal behavior as a dialog, float as a palette, etc.

You may use either a GIF or PNG image for irregularly shaped windows. If you wanttranslucency you must use PNG images. Translucency is currently only supported on
Windows and Mac OS X systems.

7.13Programming Menus & Menu Bars

Menus in LiveCode are not
a separate object type. Instead, you create a menu from either
a button or a stack, then use special commands to display
the menu or to include it in amenu bar.

This topic discusses menu bars, menus that are not in the menu bar (such as contextualmenus, popup menus, and option menus), how to make menus with special features such
as checkmarks and submenus, and how to use a stack window as a menu
for total control
over menu appearance.

To easily create menu bars that work cross-platform, choose Tools -> Menu Builder
.
See the section on the Menu Builder in the chapter on Building a User interface for more
details. The details about menu bars in this topic are needed only if you want edit menu
bars by script, for example if you want to include specific features not supported by theMenu Builder.


7.13.1 Menu Types
LiveCode supports several menu types: pulldown menus, option menus (usually called
popup menus on Mac OS and OS X), popup menus (usually
called contextual menus on
Mac OS and OS X)
, and combo boxes.

Each of these menu types is implemented by creating a button. If the button's styleproperty is set to "menu", clicking it causes a menu to appear. The button's menuMode
property determines what kind of menu is displayed.

Changed lines 3266-3318 from:
getProp expertSettings[thePropertyName]

-- The thePropertyName parameter contains the name of

-- the property that's being set

switch thePropertyName

 case "fileMenuContents"

 if the expertSettings[fileMenuContents] of the \

target is empty then return "(No items"

else pass expertSettings

break

 case "editMenuContents"

 if
the expertSettings[editMenuContents] of the \

 target is empty then return \

the noviceSettings[editMenuContents] of the target

else pass expertSettingsbreak
default
pass expertSettingsend switch
end expertSettings

As you can see from the pass and end control structures,
the name of this getProp
handler
is the same as the name of the custom property set that it controls –
"expertSettings". Because there is only one handler for all the custom properties in thisset, the handler uses the switch control structure to perform a different action for each
property that it deals with
.

Suppose
you get the "fileMenuContents" custom property:

set
the customPropertySet of button 1 to "expertSettings"
put the fileMenuContents of button 1 into me

LiveCode sends a getProp call to
the button, which causes the above handler to execute.
The property you queried – "fileMenuContents" – is placed
in the "thePropertyName"
parameter. The
handler executes the case for "fileMenuContents": if the property isempty, it returns "(No items". Otherwise, the pass control structure lets the getProp callproceed along the message path, and when it reaches the engine, LiveCode gets thecustom property.

7.11Virtual Properties

A virtual property is a custom property that exists only
in a setProp and/or getProphandler, and is never actually set. Virtual properties are never attached to the object.
Instead, they act to trigger setPropor getProp handlers that do the actual work.

When
you use the set command with a virtual property, its setProp handler is executed,
but
the setProp trigger is not passed to the engine, so the property is not attached to theobject. When you use a virtual property in an expression, its getProp handler returns a
to:
Even menu bars are created by making a pulldown-menu button for each menu, then
grouping the buttons to create a single menu bar. The menu bar can be moved to the top

of the stack window (on Unix and Windows systems). To display the menu bar in thestandard location at the top of the screen on Mac OS and OS X systems, you set thestack's menubar property to the group's name. The name of each button is displayed in
the menu bar as a menu, and pulling down a menu displays the contents of the button as alist of menu items.

7.13.2 Button Menus
You can create a button menu by dragging out one of the menu controls from the toolspalette
. However, if you want to create one by script, the easiest is to create a button and
set the style of the button to "menu". Next, you can set
the menuMode of the button to
the appropriate menu type. You can either set the menuMode
in a handler, or use theType menu in the button's property inspector to set the menu type.

To create the individual menu items that will appear in
the menu, set the button's text
property to the menu's contents, one menu item per line. You can either set this property

in a handler, or fill in the box labeled "Menu items" on the Basic Properties pane of theproperty inspector.

When you click the button, the specified menu type appears, with the text
you entered
displayed as the individual menu items in the menu.

Tip: To dynamically change
the menu's contents at the time it's displayed, put a
mouseDown handler in the button's script that puts the desired menu items into thebutton. When the menu appears, it displays the new menu items.
For menus that retain a state (such as option menus and combo boxes), the button'slabel property holds the text of the currently chosen menu item.

Handling the menuPick message

When the user chooses an item from the menu, LiveCode sends the menuPick messageto the button. The message parameter is the name of the menu item chosen. If you wantto perform an action when the user chooses a menu item, place a menuPick handler like
this one into the button's script:

on menuPick theMenuItem
switch theMenuItem
case "Name of First Item"
-- do stuff here for first item
break
case "Name of Second Item"
-- do stuff here for second item
break
case "Name of Third Item"

Changed lines 3303-3344 from:
value without referring to the object. In both cases, using the property simply executes ahandler.

You can use virtual properties to:

*

Give an object a set of behaviors
*
Compute a value for an object
*
Implement a new
property that acts like a built-in property
7.11.1 When to use virtual properties
Because they're not stored with the object
, virtual properties are transient: that is, they arere-computed every time you request them. When a custom property depends on other
properties that may be set independently, it's appropriate to use a virtual property.

For example, the following handler computes the current position of a scrollbar as apercentage (instead of an absolute number
):

getProp asPercentage -- of a scrollbar
put the endValue of the target \

- the startValue of the target into valueExtent
return the thumbPosition of me * 100 div valueExtent
end asPercentage

The "asPercentage" custom property depends on the scrollbar's thumbPosition
,
which can be changed at any time (either by the user or by a handler). Because of this, ifwe set a custom property for the object, it would have to be re-computed every time thescrollbar is updated in order to stay current. By using a virtual property, you can ensurethat the value of the property is never out of date, because the getProp handler recomputes
it every time you call for
the "asPercentage" of the scrollbar.

Virtual properties are also useful solutions when a property's value is large. Because thevirtual property isn't stored with the object, it doesn't take up disk space, and only takesup memory when it's computed.

Another reason to use a virtual property is to avoid redundancy. The following handler
sets the width of an object, not in pixels, but as
a percentage of the object's owner's
width:

setProp percentWidth newPercentage
set the width of the target to \

the width of the owner of the target \

* newPercentage div 100end percentWidth
Suppose this handler is placed in the script of a card button in a 320-pixel-wide stack. Ifyou set the button's "percentWidth" to 25, the button's width is set to 80, which is 25%
of the card's 320-pixel width. It doesn't make much sense to store an object's
percentWidth, however, because it's based on the object's width and its owner's width.

to:
-- do stuff here for third item
break
end switch
end menuPick

Changing the currently-chosen menu item

For menus that retain a state (such as option menus and combo boxes), you can changethe currently-chosen menu item by changing the button's label
property to the text of
the newly chosen item

If you change the currently-chosen menu item in option menus
, also set the button'smenuHistory property to the line number of the newly chosen item. This ensures thatthe new choice will be the one under the mouse pointer the next time the user clicks the
menu.

7.13.3 Creating Cascading Menus
To create a cascading menu (also called a submenu, pull-right menu, or hierarchicalmenu
), add a tab character to the start of menu items that you want to place in thesubmenu.

For example, the following text, when placed in a menu button, creates two menu items,

then a submenu containing two more items, and finally a last menu item:

 First Item

 Second Item

 Third Item Is A Submenu

First Item In Submenu

Second Item In Submenu

 Last Menu Item Not In Submenu

The depth of a submenu item
is determined by the number of tab characters before themenu item's name. The submenu item becomes part of the closest line above the submenu
item that has one fewer leading tab character.

This means that
the first line of a menu cannot start with a tab character, and any line in
the button's text can have at most one more tab character than the preceding line.

Important: You cannot create a cascading combo box at all, and cascading optionmenus do not work properly on all platforms. In general, you should create cascading
menus only as a part of
a pulldown menu.
Cascading menus and the menuPick message

When the user chooses a menu item in a cascading menu,
the parameter of themenuPick message contains the menu item name and the name of the submenu it's part
Changed lines 3347-3385 from:
Consider using virtual properties whenever you want to define an attribute of an object,
but it doesn't make sense to store the attribute with the object – because it would beredundant, because possible changes to the object mean it would have to be re-computed
anyway, or because the property is too large to be easily stored.

7.11.2 Handlers for
a virtual property
As you can see by looking at
the example above, a handler for a virtual property isstructured like a handler for any other custom property. The only structural difference isthat, since the handler has already done everything necessary, there's no need to actually
attach
the custom property to the object or get its value from the object. When you set avirtual property or use its value, the setProp trigger or getProp call does not reach
the engine, but is trapped by a handler first.

Virtual property setProp handlers

A setProp handler for an ordinary custom property includes the pass control structure,
allowing the setProp trigger to reach the engine and set the custom property (or else it

includes a set command that sets the property directly). A handler for a virtual property,
on the other hand, does not include the pass control structure, because a virtual property
should not be set. Since the property is set automatically when
the trigger reaches the end
of
the message path, a virtual property's handler does not pass the trigger.

If you examine an object's custom properties after setting a virtual property, you'll find

that the custom property hasn't actually been created. This happens because thesetProp handler traps the call to set the property; unless you pass the setProp trigger,
the property isn't passed to LiveCode, and the property isn't set.

Virtual property getProp handlers

Similarly, a getProp handler for an ordinary custom property either gets the property'svalue directly, or passes the getProp call so that the engine can return the property'svalue. But in the case of a virtual property, the object doesn't include the property, so thegetProp handler must return a value.

7.11.3 Creating new object properties
You can use virtual properties to create a new property that applies to all objects, or to allobjects of a particular type. Such a property acts like a built-in property, because you can
use it for any object. And because a virtual property doesn't rely on a custom property
being stored in the object, you don't need to prepare by creating the property for each newobject you create: the virtual property is computed only when you use it in an expression.

The following example describes how to implement a virtual property called
"percentWidth" that behaves like a built-in property.

Setting the "percentWidth" property

Suppose you place the "percentWidth" handler described above in a stack script instead
of in a button's script:

to:
of, separated by a vertical bar (|). For example, if the user chooses the "Second Item In
Submenu" from the menu described above,
the parameter sent with the menuPick
message is:

 Third Item Is A Submenu|Second Item In Submenu

7.13.4 Ticks, Dashes & Checks in Menus
There are several special characters that you can put at the start of
a line in the button'scontents to change the behavior of the menu item:

-A dash on
a line by itself creates a divider line

* !c checks the menu item

* !n unchecks
the menu item

* !r places a diamond at the start of
the menu item

* !u removes the diamond

If you include any of the above special characters in a submenu item
, the specialcharacter must be placed at the start of the line – before the tab characters that make it asubmenu item.

Note: You cannot create divider lines in combo boxes or in option menus on Windows
systems.
There are three other special characters that can appear anywhere in a line:


Putting the & character anywhere in a line underlines the next character and makes it thekeyboard mnemonic for that menu item on Windows systems. The & character does not
appear in the menu, and is not sent with the parameter to
the menuPick message when
you choose
the item from a menu.

Putting the / character anywhere in a line makes the next character the keyboard
equivalent for the menu item. Neither the / nor
the character following it appear in themenu, nor do they appear in the parameter to the menuPick message.

To put an & or / character in the text of a menu, double the characters: &&or //.

Putting the ( character anywhere in a line disables the menu item. To put a ( character
in a menu item without disabling it, precede it with a backslash: \(.

Note: You cannot disable lines in combo boxes or in option menus on Windowssystems.
Changed lines 3386-3424 from:
setProp percentWidth newPercentage
set the width of the target to \
the width of the owner of
the target \

* newPercentage div 100end percentWidth
Because setProp triggers use the message path, if you set
the "percentWidth" of any
object in the stack, the stack receives the setProp trigger (unless it
's trapped by another
object first). This means that if the handler is in the stack's script, you can set the"percentWidth" property of any object in the stack.

If you place the handler in a backscript, you can set the "percentWidth" of any object,
anywhere in the application.

Note: To refer to the object whose property is being set, use
the target function. The
target refers to the object that first received
the setProp trigger--the object whose
custom property is being set--even if the handler being executed is in the script of another
object.
Getting
the "percentWidth" property

The matching getProp handler, which lets you retrieve the "percentWidth"
of an object,
looks like this:

getProp percentWidth
return 100 * (the width of the target \
div the width
of the owner of the target)
end percentWidth

If you place the handler above in a card button's script, the following statement reportsthe button's width as a percentage:

put
the percentWidth of button "My Button" into field 12

For example, if the stack is 320 pixels wide and the button is 50 pixels wide, the button'swidth is 15%
of the card width, and the statement puts "15" into the field.

Like the setProp handler for this property, the getProp
handler should be placed far
along the message path. Putting it in a stack script makes the property available to allobjects in the stack; putting it in a backscript makes the property available to all objectsin the application.

Limiting the "percentWidth" property

Most built-in properties don't apply to all object types, and you might also want to createa virtual property that only applies to certain types
of objects. For example, it's not very
to:
All of the above special characters are filtered out of the parameter sent with themenuPick message when the user chooses a menu item. The parameter is the same asthe characters that are actually displayed in the menu.

Note: The font and color of a button menu is determined by the button
's font and color
properties. However, on Mac OS systems, the font and color of the option menus and
popup menus is controlled by
the operating system's settings if the lookAndFeelis set
to "Appearance Manager", rather than by the button's font and color properties.
Enabling and disabling menu items

To enable or disable a menu item in a handler, you can add or remove
the ( special
character, but it is generally easier to use
the enable menu and disable menu
commands:

enable menuItem 3 of button "My Menu"
disable menuItem 4 of me

These commands simply add or remove
the ( special character at the start of the
designated line
of the button's contents.

7.13.5 Menu Bars on Unix and Windows Systems
A menu bar is made up of a group
of menu buttons, with the menuMode property of
each button set to "pulldown".

Tip: The Menu Builder can automatically create a menu bar for you. To use
the Menu
Builder, choose Tools -> Menu Builder.
To create a menu bar by hand without using the Menu Builder:

1. Create a button for each menu, set the style
of each button to "menu", and set the
menuMode of the button to "pulldown"
. You can either set these properties in a handler,
or simply choose Object -> New Control Pulldown Menu to create each button.
2. Put
the menu items into each button's contents. In each button's script, create amenuPick handler to perform whatever actions you want to do when a menu item is
chosen.
3. Select the buttons and form them into a group, then move the group to the appropriateposition at the top
of the window. For Windows systems, set the textFont of the group
to the standard font for Windows menus, "MS Sans Serif".
Changed lines 3420-3462 from:
useful to get the width of a substack as a percentage of its main stack, or the width of acard as a percentage of the stack's width.

You can limit the property to certain object types by checking
the target object's
name:

setProp percentWidth newPercentage

 if word 1 of the name of the target is "stack" \

 or word 1 of the name of
the target is "card" \

then exit setProp

set the width of the target to \

 
the width of the owner of the target \

* newPercentage div 100end percentWidth
The first word of an object's name is
the object type, so the above revised handler
ignores setting the "percentWidth" if
the object is a card or stack.

7.12Managing Windows, Palettes and Dialogs

LiveCode provides complete control over all aspects of window management, including
moving, re-layering, and changing window mode.

7
.12.1 Moving a window
Usually, you use either the locationor rectangle property of a stack to move the
stack window.

Thelocation property specifies the center of the stack's window
, relative to the top leftcorner of the main screen. Unlike the location of controls, the location of a stack
is specified in absolute coordinates. The following statement moves a stack to the center
of the main screen:

set the location of
stack "Wave" to the screenLoc

The rectangle property of a stack specifies the position of all four edges, and can beused to resize the window as well as move it:

set the rectangle of this stack to "100,100,600,200"


Tip: To open a window at a particular place without flickering, set the stack's location or
rectangle property to the desired value either before going
to it, or in the stack’s
preOpenStack handler.
to:
Important: The buttons in your menu bar should not overlap. Overlapping buttons may
cause unexpected behavior when
the user tries to use a menu.
7.13.6 Menu Bars on Mac OS Systems
To create a Mac OS menu bar, you follow
the same steps as for a Unix and Windowsmenu bar above. This places a group of buttons, each of whose menuMode property is
set to "pulldown", at
the top of your stack window.

Next, you
set the menubar property of your stack to the name of the group. This doestwo things: it displays the menus in the menu bar at the top of the screen, and it shortensthe stack window and scrolls it up so that the group of menu buttons is not visible in thewindow. Since the menus are in the menu bar, you don't need to see them in the stack
window as well
. 

Important: If your stack has more than one card, make sure that the group is placed on
all the cards. (To place a group on a card
, choose Object menu Place Group, or use the
place command
.) This ensures that the menu bar will be accessible on all cards of the
stack, and prevents the stack from changing size as you move from card to card (toaccommodate shortening the
stack window for the menu bar group).
The default menu bar

If other stacks in your application don't have their own menu bars, set thedefaultMenubar global property to the name of your menu group, as well as setting

the stack's menubar property. The defaultMenubar is used for any stack that
doesn't have a menu bar of its own.

Tip: For a custom menu bar
to work correctly inside the LiveCode development
environment, you must set the defaultMenubar to the name of your menu group. This
overrides the LiveCode IDE menu bar. You can get the menu bar back by choosing the
pointer tool.
Button menu references

If the button is a button menu that's being displayed in the menu bar, you can use the
word "menu" to refer to it:

get menuItem 2 of menu "Edit"
-- same as 'get line 2 of button "Edit"'

Because menus are also buttons, you can use a button reference to get the sameinformation. But you may need to specify the group and stack the button is in, to avoid
ambiguity. (For example, if there is a standard button named "Edit" on the current card,

Changed lines 3455-3493 from:
You can also use associated properties to move a window. Changing a stack's bottomor
top property moves the window up or down on the screen. Changing the leftor

right property moves the window from side to side.

7.12.2 Changing a window's layer
You bring a window to the front by
using the go command:

go stack "Alpha"

If
the stack is already open, the go command brings it to the front, without changing its
mode.

To find out the
layer order of open stack windows, use the openStacks function. This
function lists all open stack windows in order from front to back.


The palette layer

Normally, palette windows float above editable windows and modeless dialog boxes. Apalette will always above a standard window, even if you bring the standard window to
the front
. This helps ensure that palettes, which usually contain tools that can be used in
any window, cannot disappear behind document windows. It's also a good reason
to makesure you design palette windows to be small, because other windows cannot be moved in
front of them if
the palette blocks part of the window.

The system palette layer

System windows--stacks whose systemWindow property is true--float above all other
windows, in every running application. This means that even if the user brings another
application to the front, your application's system windows remain in front of allwindows.

System windows are always in front of other windows, and you cannot change thisbehavior.

7.12.3 The active window
In most applications, commands are applied to the active window. Since LiveCode givesyou the flexibility to use several different window types, not all of which are editable, thecurrent
stack is not always the same as the active window. The current stack is the targetof menu choices such as View -> Go Next and is the stack specified by the expressionthis
stack.

For example, executing the find command may have unexpected results if stacks ofdifferent modes are open, because under these conditions, the search may target a stack
that is not
the frontmost window.

Finding the current stack

to:
the expression button "Edit" refers to that button, not to the one in the menu bar.)
An unambiguous button reference to a menu might look like this:


get line 2 of button "Edit" of group "Menu" of stack "Main"

The above statement produces the same information as the form
using "menu", but you
need to know the group name and possibly which stack it's in, so the menu
menuNameform is a little more convenient.

The
layer of menu buttons

For a menu bar to work properly on Mac OS and OS X systems, the menus must be in

layer order within the group. That is, the button for the File menu must be numbered 1,
the button for the Edit menu must be 2, and so on
. The Menu Builder takes care of thisautomatically; you only need to worry about layering if you're creating the menu bar by
hand.

Changing menus dynamically

If you want
to dynamically change a menu's contents with a mouseDown handler at the
time the menu is displayed, you must place
the mouseDown handler in the group'sscript. When a menu button is being displayed in the Mac OS menu bar, it does notreceive mouseDown messages, but its group does.

The editMenus property

When you set the menubar property of a stack to the name of a group, the stack isresized and scrolled up so the part of the window that holds the menus is not visible. To
reverse this action so you can see, select and edit the buttons that make up your menu bar,
set the editMenus property to true. This resizes the
stack window so the button menusare again visible, and you can use the tools in the LiveCode development environment to
make changes to them.

To scroll the stack window again so that the menus are hidden, set the editMenus
property back to false.

Special menu items

A few menu items on Mac OS and OS X are handled directly by
the operating system. To
accommodate these special menu items while allowing you to create a fully crossplatform
menu bar, LiveCode treats the last two menu items of the Help menu (for MacOS and OS X), the File menu (OS X), and the Edit menu (OS X) differently.

By following these guidelines, you can make sure your menus will appear properly on alloperating systems without having to write special code or create platform-specific menu
bars.

The Help menu and the "About This Application" menu item

When LiveCode sets up the Mac OS menu bar, it automatically makes the last button theHelp menu (regardless of the button's name). The standard Help menu items, such as

Changed lines 3500-3540 from:
The current stack--the stack that responds to commands--is designated by thedefaultStack property. To determine which stack is the current stack, use the
following rules:

1. If any stacks are opened in an editable window, the current stack is
the frontmostunlocked stack. (A stack is unlocked if its cantModify property is set to false.)
2. If there are no unlocked stacks open,
the current stack is the frontmost locked stack in
an editable window.
3. If there are no stacks open
in an editable window, the current stack is the frontmoststack in a modeless dialog box.
4. If there are no editable or modeless windows open, the current stack is the frontmostpalette.
Another way of expressing this set of rules is to say that
the current stack is the frontmost
stack with
the lowest mode property. You can find out which stack has the lowest mode
using
the topStack function.


The topStack function and
the defaultStack property:
The defaultStack property specifies which stack is the current stack. By default
, the
defaultStack is set to the topStack, although you can change the
defaultStack to any open stack.


The topStack function goes through
the open stacks first by mode, then by layer. For
example, if any editable windows are open, the topmost editable window is the
topStack
. If there are no editable windows, the topStack is the topmost modeless
dialog box, and so on.


Changing the current stack

To operate on a stack other than the current stack, set the defaultStack property to

the stack you want to target before executing the commands. Usually, thedefaultStack is the topStack, but you can change it if you want to override theusual rules about which window is active.

A note about Unix systems

If your system is set up to use pointer focus rather than click-to-type or explicit focus,

you may experience unexpected results when using LiveCode, since the current stack willchange as you move the mouse pointer. It is recommended that you configure your
system
to use explicit focus when using LiveCode or any other applications created in
LiveCode.

7.12.4 Creating a backdrop
For some applications
, you may want to create a solid or patterned backdrop behind your
application's windows. This backdrop prevents other applications' windows from being
to:
"About This Application" and "Show Balloons" on Mac OS Classic, are included for you
automatically; you don't need to include them in your Help menu button, and you can't
eliminate them from the Help menu.

LiveCode moves
the last menu item in the Help menu to the "About This Application"
position. On Mac OS systems, this is the first menu item in
the Apple menu. On OS Xsystems, it's the first menu item in the Application menu. Therefore, the last menu item in
your Help menu button should be an appropriate "About" item. The menu item above itmust be a divider line (a dash), and above that must be at least one menu item to beplaced in the Help menu.

The File menu and
the "Quit" menu item

On OS X systems,
the "Quit" menu item is normally placed in the Application menu
(which is maintained by
the operating system) rather than in the File menu, as is standard
on other platforms. To accommodate this user-interface standard
, LiveCode removes thelast two menu items of the File menu when a standalone application is running on an OSX system. Therefore, the last menu item in your File menu button should be "Quit". Themenu item above it should be a divider line (a dash).

The Edit menu and the "Preferences" menu item

On OS X systems, the "Preferences" menu item is also normally placed in theApplication menu. To accommodate this user-interface standard, LiveCode removes thelast two menu items of
the Edit menu when a standalone application is running on an OSX system. Therefore, the last menu item in your Edit menu button should be"Preferences". The menu item above it should be a divider line (a dash).

Note: The Preferences menu item is treated in this special way only if its name starts

with the string "Preferences".
Tip: If your application's user interface is presented in a language other than English, set
the name of the Edit menu button
to "Edit", and set its label to the correct translation.
This ensures that the engine can find the Edit menu
, while making sure that the menu is
shown in the correct language.

Choosing the special menu items

When the user chooses any of these special menu items, a menuPick message is sent to
the button that the menu item is contained in. This ensures that your button scripts willwork on all platforms, even if LiveCode displays a menu item in a different menu to
comply with user-interface guidelines.

For example, if the user chooses "About This Application" from the Apple menu on aMac OS system, a menuPick message is sent to the Help menu button, with "About

Changed lines 3533-3570 from:
seen – although it does not close those windows – so it's appropriate for applications likea game or kiosk, where the user doesn't need to see other applications and where you
want to keep distractions to a minimum.

Note: In LiveCode Media edition, you cannot turn off the backdrop property.
To
create a backdrop, you set the backdrop property to either a valid color reference,
or the ID of an image you want to use as a tiled pattern:

set the backdrop to "#99FF66" --
a color
set the backdrop to 1943 -- an image ID

In the LiveCode development environment, you can create a backdrop by choosing View
-> Backdrop. Use the Preferences dialog box to specify a backdrop color to use.

7.12.5 Open, Closed,
and Hidden Windows
Each open stack is displayed in a
stack window. A stack can be open without being
visible, and can be loaded into memory without being open.

Hidden stacks

A stack window
can be either shown or hidden, depending on the stack's visible
property. This means a window can be open without being visible on the screen.

Tip: To list all open stacks, whether they
're visible or hidden, use the openStacks
function.
Loaded stacks

A stack
can also be loaded into memory without actually being open. A stack whosewindow is closed (not just hidden) is not listed by the openStacks function. However,
it takes up memory, and its objects are accessible
to other stacks. For example, if a closed
stack that's loaded into memory contains a certain image, you can use the image as abutton icon in another stack.

A stack can be loaded into memory without being open under any of the following

conditions:

A
handler in another stack referred to a property of the closed stack. This automatically
loads the referenced stack into memory.

The
stack is in the same stack file as another stack that is open.
to:
This Application" as its parameter. You handle the message for the About menu item in
the Help menu button's script
, even though LiveCode displays this menu item in adifferent menu on the Mac.

7.13.7 Stack Menus
Button menus can be used for most kinds of standard menus. However, if you want to

create a menu with a feature that is not supported by button menus--for example, if you
want a popup menu that provides pictures, rather than text, as the choices--you can createa menu from
a stack.

Creating a stack menu

To create a stack menu, you create a stack with a control for each menu item. Since thestack menu is a stack and each menu item is an object, the menu items receive mousemessages such as mouseEnter,mouseLeave,
and mouseUp.

When the user chooses an item from the
stack menu, a mouseUp message is sent to thatcontrol. To respond to a menu item choice, instead of handling the menuPick message,
you
can place a mouseUp handler in the script of the object.

To create a stack menu that looks like a standard menu, create a button in the stack for
each menu item. The button
's autoArm and armBorder properties should be set to
true. Or you
can choose "Menu Item" item in the "New Control" submenu of the Objectmenu to create a button with its properties set to the appropriate values.

Be sure to set the rectangle of the stack
to the appropriate size for the menu.
Remember, when you open the menu, the stack will be displayed exactly as it looks in an
editable window.

Finally, either set the menuName property of a button to a reference to the stack, or place

a mouseDown handler containing a pulldown, popup, or option command in the
script of an object. When you click the button or object, the
stack menu appears.

Displaying a
stack menu

Stack menus can be associated with a button, just like button menus. But when you click
the button, instead of displaying a menu with the button's contents, LiveCode displays astack with the behavior of a menu.

You can also display a stack menu without associating it with a button, by using thepulldown, popup, or option command. Normally, you use these commands in a
mouseDown handler, so that the menu appears under the mouse pointer:

on mouseDown -- in card script

 popup stack "My Menu Panel"
end mouseDown

Changed lines 3574-3612 from:
The stack was opened and then closed, and its destroyStack property is set to false.
(If the destroyStack property is false, the stack is closed, but not unloaded, when its
window is closed.)

Tip
: To list all stacks in memory, whether they're open or closed, use the
revLoadedStacks function.

7.12.6 The states of a stack
A stack, then, can be in any of four states:

Open and visible:The stack is loaded into memory
, its window is open, and the window
is visible.

Open and hidden:The stack is loaded into memory
, its window is open, but the windowis hidden. The stack is listed in the Window menu and in the Application Browser.

Closed but loaded into memory:The stack is loaded into memory, but its window is not
open and it is not listed by the openStacks function or in
the Window menu.
However, its objects are still available
to other stacks, and it is listed in the Application
Browser. A stack that is closed but loaded into memory has a mode property of zero.

To remove such a stack from memory, choose Tools -> Application Browser, find
the
stack's name, and Control-click it
(Mac OS or OS X) or Right-click it (Unix or
Windows) in
the Application Browser window and choose "Close and Remove fromMemory" from the contextual menu.

Closed:The stack is not loaded into memory and has no effect on other stacks
.

7.12.7 Window Types and the Mode Property
In a script, you can find out a stack window's type by checking the stack's mode
property. This read-only property reports a number that depends
on the window type. Forexample, the mode of an editable window is 1, and the mode of a palette is 4.

You can use
the mode property in a script to check what sort of window a stack is being
displayed in:

if the mode of this stack is 5 then -- modal dialog box
close this stack
else -- some other type of windowbeepend if

For complete information about the possible values of the mode property, see its entry in
the LiveCode Dictionary
.
to:
7.13.8 Displaying Context Sensitive Menus
There are also several commands to display a context menu
. Usually, you use thesecommands in a mouseDown handler – normally either in your card or stack script:

popup command
: opens a stack as a popup menu
pulldown command: opens a stack as a pulldown menu

option command: opens a stack as an option menu


Note: If you set a button's menuName property to the name of a stack
, the stack menu
is displayed automatically when the user clicks the button. You need the popup
,
pulldown, and option commands only if you want to display a stack menu in some way
other than when a button is clicked.
7.14Searching and Navigating Cards using the Find Command

The find command in LiveCode allows you to search the fields of the current stack, then
navigate to and highlight
the results of the search automatically. While it is possible to
build such a command using the comparison features detailed in the chapter Processing
Text and Data, for most purposes the find command provides a complete, pre-built
solution.

find [form] textToFind [in field]

The form can be one of
the following:
normal
characters or character
(or chars or char)
words
or word
stringwhole


If no form is specified,
the find normal form is used.

The textToFind is any expression that evaluates to a string.

The field is any expression that evaluates to a field reference
. If the field is not specified,
the find command searches all the fields in the current stack (except fields whosedontSearch property is set to true).

find "heart"
find string "beat must go
on" in field "Quotes"


When
the find command finds a match, it highlights the match on the screen – ifnecessary navigating to the card that contains the match and scrolling the field so the textis in view.
Changed lines 3616-3656 from:
7.12.8 Window Appearance
Details of a window's appearance, such as
the height of its title bar and the background
color or pattern in the window itself, are mainly determined by
the stack's mode. Thereare a few additional elements of window appearance that you can control with specificproperties.

The metal property

On OS X systems, you use a stack's metal property to give the stack window a textured
metal appearance. This metal appearance applies to the stack's title bar and itsbackground.

Tip: The metal appearance, in general, should be used only for
the main window of an
application, and only for windows that represent a physical media device such as
a CD
player. See Apple's Aqua user-interface guidelines for more information.
Window background color

The background color or pattern of a window's content area--
the part that isn't part of thetitle bar--is determined by the window type and operating system, by default. For
example, on OS X systems, a striped background appears in palettes
and modeless dialog
boxes.

If you want a window to have a specific color or pattern, you can set
the stack'sbackgroundColoror backgroundPattern property:

set the backgroundColor of stack "Alpha" to "aliceblue"
set the backgroundPattern of stack "Beta" to 2452 -- img ID

This color or pattern overrides the usual color or background pattern.

7.12.9 The Decorations Property
Most of the properties that pertain to a window's appearance can also be set in the stack's

decorations property. The decorations of a stack consists of a comma-separated
list of decorations:


set the decorations of stack "Gamma" to "title,minimize"

The statement above sets the stack'sminimizeBox property to true, as well as showing
its title bar, and sets other stack properties (maximizeBox, closeBox, metal)
to
false. Conversely, if you set a stack's minimizeBox property to true, its
decorations property is changed to include "minimize" as one of its items. In this
way, the decorations property of a stack interacts with its closeBox,
minimizeBox, zoomBox, metal, shadow, and systemWindow properties.

The decorations property and menu bars in a window

to:
The find command can also be used to return the location of the text that was found.
To reset the find command so that it starts searching at
the beginning again:

find empty

For more details on the find command and associated options, see the find command in
the LiveCode Dictionary.

7.15Using Drag and Drop

LiveCode allows you complete control over drag and drop – both within LiveCodewindows and between LiveCode and other applications.

7.15.1 Initiating a Drag Drop
To begin a drag and drop operation, the user clicks and holds
the mouse pointer. Thissends a mouseDown message to the object.

If you drag from within a field,
a dragStart message is sent. To allow drags from alocked field or from another object type, in the object's mouseDown handler, set the
dragData property to the data you want to drag. When there is a value in the
dragData, a drag and drop is initiated when the mouse is clicked
and then moved.

set the dragData["text"] to "text being dragged"

You can set the dragData to contain any of
the following types of data:

text The plain text being dragged.

HTML The styled text being dragged, in the same format asthe htmlText
RTF The styled text being dragged, in the same format asthe RTFText
Unicode The text being dragged, in the same format as the
unicodeText
image The data of an image (in PNG format)
files The name and location
of the file or files being
dragged, one per line

Note: LiveCode automatically handles the mechanics of dragging and dropping text
between and within unlocked fields. To support this type of drag and drop operation, you
don't need
to do any scripting.
For more details, see the entries for dragStart and dragData in the LiveCode Dictionary.

Changed lines 3654-3695 from:
On Unix and Windows systems, the menu bar appears at the top of the window. On thesesystems, whether a window displays its menu bar is determined by whether the stack'sdecorations property includes "menu":

set the decorations of this stack to "title,menu"

On Mac OS and OS X systems,
the menu bar appears at the top of the screen, outside any
window. On these systems,
the "menu" decoration has no effect.

Title bar


The user drags the title bar of a window to move the window around the screen. In
general, if
the title bar is not displayed, the user cannot move the window. You use thedecorations property (discussed below) to hide and show a window's title bar.

When the user drags the window, LiveCode sends a moveStack
message to the current
card.

The decorations property affects only whether
the window can be moved by
dragging it. Even if a stack's decorations property does not include
the title bar
decoration, you can still set a stack's location, rectangle, and related properties to
move or resize the window.

Window title

The title that appears in the title bar of a window is determined by
the stack's label
property. If you change a stack's label in a script
, the window's title is immediately
updated.

If the label
is empty, the title bar displays the stack's name property. (If the stack is in
an editable window whose cantModify is false, an asterisk appears after the windowtitle to indicate this, and if
the stack has more than one card, the card number also appearsin the window title. These indicators do not appear if the stack has alabel.)

Because
the window title is determined by the stack's label property instead of its
name property, you have a great deal of flexibility in changing window title. Your scriptsrefer to
the stack by its name--which doesn't need to change--not its label, so you can
change the window title without changing any scripts that refer to the stack.

The close box

The close box allows the user to close the window by clicking it. To hide or show theclose box, you set the stack's closeBox property:

set the closeBox of stack "Bravo" to false

When the user clicks the close box, LiveCode sends a closeStackRequest message,
followed by a closeStack message, to the current card
.
to:
7.15.2 Tracking During a Drag Drop Operation
You can use
the dragEnter message to show an outline around an object or change thecursor when the mouse moves into it during a drag operation.

on dragEnter -- show a green outline around the drop targetset the borderColor of the target to "green"
end dragEnter

You can use
the dragMove message to update the screen whenever the cursor movesduring a drag and drop operation.

on dragMove -- in a field script

-- set the cursor so it shows you can only drop onto a linkif
the textStyle of the mouseChunk contains "link"
then set
the cursor to the ID of image "Drop Here"
else set the cursor to the ID of image "Dont Drop"

end dragMove

You can use the dragLeave
message to remove any outline around an object or changethe cursor when the mouse moves out of an object during a drag operation.

on dragLeave
-- remove any outline around
the drop no-longer-targetset the borderColor of the target to empty

end dragLeave

For more details, see the entries for dragEnter, dragMove and dragLeave in the LiveCode
Dictionary.

7.15.3 Responding to a Drag and Drop
To perform an action when
the user drops data onto a locked field or another object type,
you handle the dragDrop message.


The dragDrop message
is sent when the user drops data on an object.

on dragDrop -- check whether a file is being dropped
if the dragData["files"] is empty then beep 2pass dragDrop

end dragDrop

You must set
the acceptDrop property to true before a drop will be allowed. Usually,
you set this property to true in a dragEnter handler.

You can use
the dragDestination function to retrieve the long id of the object thatthe dragged data was dropped on. You can use the dragSource function to retrieve the
long id of
the object that was the source of the drag.
Changed lines 3698-3735 from:
The closeBox property affects only whether the window can be closed by clicking.
Even if a stack's closeBox property is false, you can still use the close command in a
handler or the message box to close the window.

The minimize box or collapse box

The terminology and behavior of this part of the title bar varies depending on platform.
On Mac OS systems,
the collapse box shrinks the window so only its title bar is shown.
The minimize box (OS X and Windows systems) or iconify box (Unix systems) shrinksthe window to a desktop icon.

To hide or show the minimize box or collapse box, you set the stack's minimizeBox
property:

set
the minimizeBox of this stack to true

that appears when the stack is minimized.
Tip: On OS X and Unix systems, you can set a stack's icon property to specify the icon

When the user clicks the minimize box or collapse box, LiveCode sends an
iconifyStack message to
the current card.

The maximize box or zoom box

The terminology and behavior of this part of the title bar varies depending on platform.

On Mac OS and OS X systems, the zoom box switches the window between its currentsize and maximum size. The maximize box (Unix and Windows systems) expands thewindow to its maximum size.

To hide or show the zoom box or maximize box, you set the stack's zoomBox property:

set the zoomBox of stack "Hello" to false

When the user clicks the zoom box or maximize box, LiveCode sends a resizeStack
message to the current card.

7.12.10 Making a stack resizable
A stack's resizable property determines whether the user can change its size by dragging
a corner or edge (depending on operating system) of the stack window.

Tip: To move and resize controls automatically to fit when a stack is resized, use the"Geometry" pane in the control's property inspector.
to:
When a drag drop has been completed, a dragEnd message is sent to the object the drag
and drop started from.

on dragEnd -- remove data being dragged

delete the dragSourceend dragEnd

You can use the dropChunk function to retrieve the location of the text that was
dropped in a field. For example, you could select the text that was dropped by doing thefollowing:

select
the dropChunk

For more details, see the entries for dragDrop, dragEnter, dragDestination, dragEnd,

dragSource , dropChunk and acceptDrop in the LiveCode Dictionary.

7.15.4 Prevent Dragging and Dropping
to a Field
You prevent dropping data into a field during a drag and drop by setting theacceptDrop property to false when
the mouse pointer enters the field.

If the acceptDrop is set to false, when you drop data, no dragDrop message is sentto the field. Since the drop is automatically processed only when LiveCode receives adragDrop message, this prevents the usual automatic drop behavior.

Usually, you should set
the acceptDrop in a dragEnter handler, as in the following
example:

on dragEnter -- in a field script

 set the acceptDrop to falseend dragEnter


If you want to prevent dragging text within a field, intercept
the dragStart message:

on dragStart

-- do nothingend dragStart

For more details, see the entries for acceptDrop, dragDrop and dragEnter in the

LiveCode Dictionary.
Changed lines 3735-3773 from:
Some stack modes cannot be resized, regardless of the setting of the stack's resizable
property. Modal dialog boxes, sheets, and drawers cannot be resized by the user, and do
not display a resize box.

The resizable property affects only whether the window can be resized by dragging acorner or edge
. Even if a stack's resizable property is set to false, you can still set a
stack's location, rectangle, and related properties to move or resize the window.

When the user resizes a stack, LiveCode sends a resizeStack message to
the current card.

7.12.11 Irregularly-Shaped and Translucent Windows
You can set a stack’s windowShape property
to the transparent, or alpha channel of an
image that has been imported together with its alpha channel. This allows you to create awindow with "holes" or a window with variable translucency. You can apply a shape to
any type
of stack, regardless of the mode it is opened, allowing such a window to exhibitmodal behavior as a dialog, float as a palette, etc.

You may use either a GIF or PNG image for irregularly shaped windows. If you wanttranslucency you must use PNG images. Translucency is currently only supported on
Windows and Mac OS X systems.

7.13Programming Menus & Menu Bars

Menus in LiveCode are not a separate object type. Instead
, you create a menu from either
a button or a stack, then use special commands to display the menu or to include it in amenu bar.

This topic discusses menu bars, menus that are not
in the menu bar (such as contextualmenus, popup menus, and option menus), how to make menus with special features such
as checkmarks and submenus, and how to use a stack window as a menu for total control
over menu appearance.

To easily create menu bars that work cross-platform, choose Tools -> Menu Builder.
See the section on the Menu Builder in the chapter on Building a User interface for more
details. The details about menu bars in this topic are needed only if you want edit menu
bars by script, for example if you want to include specific features not supported by theMenu Builder.

7.13.1 Menu Types
LiveCode supports several menu types: pulldown menus, option menus (usually called
popup menus on Mac OS and OS X), popup menus (usually called contextual menus on
Mac OS and OS X), and combo boxes.

Each of these menu types is implemented by creating a button. If the button's styleproperty is set to "menu", clicking it causes a menu to appear. The button's menuMode
property determines what kind of menu is displayed
.
to:
Chapter 8 Working With Databases

With the LiveCode Database library, your application can communicate with externalSQL databases. (Database access is not available in LiveCode Media.) You can get datafrom single-user and multi-user databases, update data in them, get information about thedatabase structure, and display data from the database in your stack
. And with theDatabase Query Builder, you can automate the process of querying a database and
populating fields with the data, with no scripting required. For a discussion of when it isappropriate to use an external database with LiveCode, see the topic When to Use aDatabase in Chapter 2.

This chapter discusses how
to install necessary software to communicate with databases,
how to set up automatic database queries using the Database Query Builder, and how to
use the Database library to communicate between LiveCode and a database.

This topic does not include discussion
of how to set up and create a SQL database, which
is beyond the scope of the LiveCode documentation.

To fully understand this topic, you should know how to write short scripts and should
understand the basic concepts of SQL databases (rows and columns, database cursors,
and SQL queries).

A few terms used in this topic, such as "field" and "cursor", are part of the standard
terminology for working with databases
, but have a different meaning in the context ofLiveCode development. When going back and forth between database work and moregeneral application development, be sure you understand which meaning is applicable in
the context you're currently working
in. When referring to database-specific terms, thedocumentation usually uses phrases like "database field" or "database cursor" to remind
you of the context. See the Glossary within the product documentation for definitions ofany term you are unsure of
.
Changed lines 3757-3792 from:
Even menu bars are created by making a pulldown-menu button for each menu, then
grouping the buttons to create a single menu bar. The menu bar
can be moved to the top
of the stack window (on Unix and Windows systems). To display
the menu bar in thestandard location at the top of the screen on Mac OS and OS X systems, you set thestack's menubar property to the group's name. The name of each button is displayed in
the menu bar as a menu, and pulling down a menu displays the contents of
the button as alist of menu items.

7.13.2 Button Menus
You can create a button menu by dragging out one of the menu controls from the toolspalette. However, if you want to create one by script, the easiest is to create a button and
set the style of
the button to "menu". Next, you can set the menuMode of the button to
the appropriate menu type. You can either set the menuMode in a handler, or use theType menu
in the button's property inspector to set the menu type.

To create the individual menu items that will appear
in the menu, set the button's text
property to
the menu's contents, one menu item per line. You can either set this property
in a handler, or fill in the box labeled "Menu items" on
the Basic Properties pane of theproperty inspector.

When you click the button, the specified menu type appears, with the text you entered
displayed as the individual menu items in the menu.

Tip: To dynamically change the menu's contents at the time it's displayed, put a
mouseDown handler in the button's script that puts the desired menu items into thebutton. When the menu appears
, it displays the new menu items.
For menus that retain a state (such as option menus and combo boxes), the button'slabel property holds the text of the currently chosen menu item.

Handling the menuPick message

When the user chooses an item from the menu, LiveCode sends the menuPick messageto the button. The message parameter is the
name of the menu item chosen. If you wantto perform an action when the user chooses a menu item, place a menuPick handler like
this one into the button's script:

on menuPick theMenuItem
switch theMenuItem
case "Name of First Item"
-- do stuff here for first item
break
case "Name of Second Item"
-- do stuff here for second item
break
case "Name of Third Item"

to:
8.1 Introduction to Database Access
A database is an external resource that holds information, structured in a special form for
quick access and retrieval. Databases
can be:

*
any size from small to extremely large

*
located on the same system as
the application or on a remote server
*
accessible by one user at a time or by many users at once
8.1.1 SQL Databases
A SQL database is a database that you access and control using SQL, a standard
database-access language which is widely supported. You use SQL queries (statements in

the SQL language) to specify the part of the database you want to work with, to get data,
or to make changes to the database.

LiveCode's database access is fully-featured. You can send any SQL statement to adatabase. You can open multiple databases (or multiple connections to
the samedatabase), maintain multiple record sets (database cursors) per connection, and send and
receive binary data as well as text. You can do all this using the Database Query Builder,
or
in scripts that use the commands and functions in the Database library.

To see a list of LiveCode terms
in the Database library, open the Dictionary, and type
"database" into
the search filter field. You can also find a interactive workshop and
tutorial materials on our web site at:

http://www.runrev.com/developers/lessons-and-tutorials/explore-livecode/databases/

8.1.2 Why use an External Database?
See
the section on When to use a Database in Chapter 2.

8.1.3 The Basics of Database Structure
A database is built of records, which in turn are built out of database fields. A field is thesmallest part of a database that can be separately addressed. Each database field containsa particular kind of information. This might be a name, a file path, a picture
, or any other
kind of information
. Each record contains one value for each of its fields. A set of records
is called a database table, and one or more tables comprise a database.

Here's an example: suppose you have a database of customers for your business. Thefields of this database might include the customer
name, a unique customer ID number,
and shipping address. Each record consists of
the information for a single customer, so
each record has a different customer name, shipping address, and so on.

Changed lines 3796-3838 from:
-- do stuff here for third item
break
end switch
end menuPick

Changing the currently-chosen menu item

For menus that retain a state (such as option menus and combo boxes), you can changethe currently-chosen menu item by changing the button's label property to the text of
the newly chosen item

If you change the currently-chosen menu item in option menus, also set the button'smenuHistory property to
the line number of the newly chosen item. This ensures thatthe new choice will be the one under the mouse pointer the next time the user clicks the
menu.

7.13.3 Creating Cascading Menus
To create
a cascading menu (also called a submenu, pull-right menu, or hierarchicalmenu), add a tab character to the start of menu items that you want to place in thesubmenu.

For
example, the following text, when placed in a menu button, creates two menu items,
then a submenu containing two more items
, and finally a last menu item:

 First Item

 Second Item

 Third Item Is A Submenu

First Item In Submenu

Second Item In Submenu

 Last Menu Item Not In Submenu


The depth
of a submenu item is determined by the number of tab characters before themenu item's name. The submenu item becomes part of the closest line above the submenu
item that has
one fewer leading tab character.

This means that the first line
of a menu cannot start with a tab character, and any line in
the button's text can have at most one more tab character than the preceding line.

Important: You cannot create a cascading combo box at all, and cascading optionmenus do not work properly on all platforms. In general, you should create cascading
menus only as a part of a pulldown menu.
Cascading menus and
the menuPick message

When the user chooses a menu item
in a cascading menu, the parameter of themenuPick message contains the menu item name and the name of the submenu it's part
to:
Note: You may have noticed that the database structure being described resembles amultiple-card stack that has the same fields on each card. A database field is like a field
in a stack, and a record is like a card. A stack set up this way can act as a database, in
fact, but lacks some of the features of an external database, such as
the ability to performSQL queries and the ability to perform robustly when accessed by more than one user.
You can also think of
the set of customer records as a grid (like a spreadsheet). Each rowis a record, and each column is a field, so each cell in the grid contains a different pieceof information about a particular customer. Here's an example:

ID

Customer Name

Address

Country
123 Jane Jones 234 E. Street U.K.
836 Acme Corporation PO Box 23788 USA
823 CanCo
, Inc. 1 CanCo Blvd. Japan

Figure 58 – Example Database Grid

There are three rows in this grid (each is the record for a particular customer) and four
columns (each is one
of the fields).

A row of
the database means one single customer record, which has one value for each
field. A column of the database means
the set of all values for one of the fields, one for
each record (for example, the set
of all customer addresses).

More generally, each row describes one of the things
in the database, and each column
describes a particular state for each thing in
the database.

The set of all customer records makes a table. Your database might include only thistable, or it might include other related tables, such as a list of all sales. You can also
connect related data from different tables of
the same database. For example, if each
record
in the Sales table includes the ID number of the customer who bought the product,
you can link all
the sales records for a customer to that customer's record in theCustomers table.

8.1.4 SQL and Record Sets – Database Cursors
SQL works primarily with sets of records, rather than individual rows. When you send aSQL query to a database, the query typically selects certain records which you can
perform further operations on. The set of records resulting from a SQL query is called adatabase cursor, or record set. SQL queries let you describe the characteristics of therecords you require, instead of processing each record one by one to find out whether itmatches your criteria.

For example, consider the customer table we talked about in the previous section. To
work with only US customers, you can write a SQL query that selects only records wherethe country field is "USA". This subset of records then becomes a record set. You can

Changed lines 3837-3874 from:
of, separated by a vertical bar (|). For example, if the user chooses the "Second Item In
Submenu" from the menu described above,
the parameter sent with the menuPick
message is:

 Third Item Is A Submenu|Second Item In Submenu

7.13.4 Ticks, Dashes & Checks in Menus
There are several special characters that you can put at the start of a line in the button'scontents to change the behavior of the menu item:

-A dash on a line by itself creates a divider line

* !c checks
the menu item

* !n unchecks the menu item

* !r places a diamond at the start of the menu item

* !u removes the diamond

If you include any of the above special characters in a submenu item, the specialcharacter must be placed at the start of
the line – before the tab characters that make it asubmenu item.

Note:
You cannot create divider lines in combo boxes or in option menus on Windows
systems.
There are three other special characters that can appear anywhere in a line:

Putting
the & character anywhere in a line underlines the next character and makes it thekeyboard mnemonic for that menu item on Windows systems. The & character does not
appear in the menu
, and is not sent with the parameter to the menuPick message when
you choose
the item from a menu.

Putting
the / character anywhere in a line makes the next character the keyboard
equivalent for the menu item. Neither the / nor the character following it appear in themenu, nor do they appear in the parameter to the menuPick message.

To put an & or / character in the text of a menu, double the characters: &&or //.

Putting the ( character anywhere in a line disables the menu item
. To put a ( character
in a menu item without disabling it, precede it with a backslash: \(.

Note: You cannot disable lines in combo boxes or in option menus on Windowssystems.
to:
find out more about the fields and records contained in this record set, and move fromrecord to record within this subset of the database. You can create more than one record
set to work with more than one set of records at a time.

Note: Different database implementations have different limitations on movementwithin a record set. For example, some databases won't let you move backward within a
record set: instead, you must start at the first record and move forward in order to

examine the data.
8.1.5 Choosing a Database
LiveCode directly supports the following database implementations:
Oracle
MySQLSQLitePostgreSQLValentina

LiveCode also supports connecting to a database via ODBC. You can use ODBC to useAccess, FileMaker, MS SQL Server and many other database implementations. Seebelow for more information about ODBC.

LiveCode's database commands and functions use
the same syntax regardless of whattype of database you are connecting to. You don't need to learn a separate databaselanguage for each type. Instead, when you first open a database with therevOpenDatabase function, you specify the type as one of the parameters so LiveCodeknows what type of database it's dealing with. The Database library handles the details ofeach type behind the scenes for you.

When you use the Database Query Builder
, you simply select the database type you want
to use. Like the Database library,
the Database Query Builder handles the details for you.
You can easily switch between database types.

8.2 Reasons to Choose a Database Type
Which type of database to choose depends on a number of factors. If you need to work
with an existing database, or already have a database manager installed, the decision ismade for you. Likewise, if you're already an expert at a particular databaseimplementation, you'll probably prefer to go on using that one
.

Other factors in your choice may include price, performance, licensing model(commercial or open source), and platform support. If your users are on a particular set ofplatforms, you'll need to choose a database that is supported on all those platforms.
Runtime do not endorse any particular database type, the information provided on thedifferent types is for informational purposes only.

Changed lines 3864-3896 from:
All of the above special characters are filtered out of the parameter sent with themenuPick message when the user chooses a menu item. The parameter is the same asthe characters that are actually displayed in the menu.

Note: The font and color of a button menu is determined by the button's font and color
properties. However, on Mac OS systems, the font and color of the option menus and
popup menus is controlled by the operating system's settings if
the lookAndFeelis set
to "Appearance Manager", rather than by the button's font and color properties.
Enabling and disabling menu items

To enable or disable a menu item in a handler,
you can add or remove the ( special
character, but it is generally easier to use the enable menu and disable menu
commands:

enable menuItem 3 of button "My Menu"
disable menuItem 4 of me

These commands simply add or remove the
( special character at the start of the
designated line of the button's contents
. 

7.13.5 Menu Bars on Unix and Windows Systems
A menu bar is made up of a group of menu buttons, with
the menuMode property of
each button set to "pulldown".

Tip: The Menu Builder can automatically create a menu bar for you. To use the Menu
Builder, choose Tools -> Menu Builder.
To create a menu bar by hand without using
the Menu Builder:

1. Create a button
for each menu, set the style of each button to "menu", and set the
menuMode
of the button to "pulldown". You can either set these properties in a handler,
or simply choose Object -> New Control Pulldown Menu to create each button.
2. Put the menu items into each button's contents. In each button's script, create amenuPick handler to perform whatever actions you want to do when a menu item is
chosen
.
3. Select the buttons and form them into a group, then move the group to the appropriateposition at
the top of the window. For Windows systems, set the textFont of the group
to the standard font for Windows menus, "MS Sans Serif".
to:
8.2.1 Overview of ODBC
Open Database Connectivity (ODBC) is a system that allows developers to access any
type of compatible database in
a standard way.

To communicate with a database, you usually have to add code that uses
the database's
own proprietary protocols. Without ODBC, in order to create a program that can
communicate with--for example--FileMaker, Access, and Oracle databases, LiveCodewould have to include code for three different database protocols. With ODBC, LiveCodecan communicate with any of these database types using
the same code.

ODBC Managers

To work with databases through ODBC, you need two pieces of software: an ODBC
manager, plus a database driver for the specific database type
you're using.

Windows 2000 and Windows XP, and OS X version 10.2 and later, include ODBC
software with the operating system. For earlier versions, and for Mac OS and Unix
systems, you can download an ODBC manager and a set of drivers.
(See the section
below titled "Software for Database Access" for more information.)

8
.2.2 Performance for Direct Access Versus ODBC Access
Typically, accessing a database via ODBC takes more configuration and is slower than
accessing
the database directly. For this reason, LiveCode provides the ability to accessMySQL, PostgreSQL and Oracle databases directly without going through the ODBC
protocol. This ability will be valuable for anyone doing complex or extensiveprofessional database work.

The syntax of
the functions in the Database library is identical for all database types, so
you do not need
to rewrite your scripts to take advantage of the increased efficiency ofdirect access.

8.3 Software for Database Access
To provide connectivity to databases, LiveCode works with database drivers--softwarethat translates application requests into the protocol required by a specific database.

8.3.1 Finding Database Drivers
Database drivers for certain database types are included in the LiveCode distribution.
(The list of included database types depends on the platform
.) The sections below listwhich database drivers are included with which platforms.

If you have installed LiveCode, you have all
the software needed to use the included
database types. For other database types, you will need to obtain the appropriate databasedrivers before you can work with those databases.

Changed lines 3901-3934 from:
Important: The buttons in your menu bar should not overlap. Overlapping buttons may
cause unexpected behavior when the user tries to use a menu.
7.13.6 Menu Bars on Mac OS Systems
To create a Mac OS menu bar, you follow the same steps as
for a Unix and Windowsmenu bar above. This places a group of buttons, each of whose menuMode property is
set to "pulldown"
, at the top of your stack window. 

Next, you set the menubar property of your stack to the name of the group
. This doestwo things: it displays the menus in the menu bar at the top of the screen, and it shortensthe stack window and scrolls it up so that the group of menu buttons is not visible in thewindow. Since the menus are in the menu bar, you don't need to see them in the stack
window as well.

Important: If your stack has more than one card, make sure that the group is placed on
all the cards. (To place a group on a card, choose Object menu Place Group, or use the

place command.) This ensures that the menu bar will be accessible on all cards of the
stack, and prevents
the stack from changing size as you move from card to card (toaccommodate shortening the stack window for the menu bar group).
The default menu bar

If other stacks in your application don't have their own menu bars, set thedefaultMenubar global property to the name of your menu group, as well as setting
the stack's menubar property. The defaultMenubar is used for any stack that
doesn't have a menu bar of its own.

Tip: For a custom menu bar to work correctly inside the LiveCode development
environment, you must set the defaultMenubar to the name of your menu group. This
overrides the LiveCode IDE menu bar. You can get the menu bar back by choosing the
pointer tool.
Button menu references

If the button is a button menu that's being displayed in the menu bar, you can use the
word "menu" to refer to it:

get menuItem 2 of menu "Edit"
-- same as 'get line 2 of button "Edit"'

Because menus are also buttons, you can use a button reference to get the sameinformation. But you may need to specify the group and stack the button is in, to avoid
ambiguity. (For example, if there is a standard button named "Edit" on the current card,

to:
Important: This section includes links to third-party web sites and contains information
about third-party software. This information is provided for your convenience, but
RunRev is not responsible for the software packages and sites referenced. Runtime
regrets that it cannot provide any support
for installation and configuration of any
databasae.
8.3.2 MySQL
MySQL database drivers are included as part of the LiveCode installation on Linux
, MacOS X, and Windows systems.

8
.3.3 Oracle
LiveCode includes drivers for Oracle on Windows and (currently) PPC Mac OS X
.

To obtain an Oracle database driver for your platform, visit the Oracle web site athttp://www.oracle.com.

8.3.4 PostgreSQL
A PostgreSQL database driver is included as part of the LiveCode installation on Linux,
Mac OS X and Windows systems.

8
.3.5 SQLite
Drivers for accessing this database are included with LiveCode. No additional installation
is necessary.

8.3.6 ODBC managers and database drivers
To use a database via ODBC, you must install the necessary ODBC software for your
platform. (Some operating systems include an ODBC installation.) ODBC softwareincludes one or more database drivers, plus an ODBC manager utility.


ODBC on Windows systems

Windows 2000 and Windows XP include the MDAC (Microsoft Data AccessComponents) package as part of
the standard system installation. To configure ODBC on
Windows systems, use the ODBC Data Sources control panel.

For earlier versions of Windows, you can download MDAC from the Microsoft web siteat http://www.microsoft.com/data/download.htm.

ODBC on Mac OS X systems

OS X version 10.2 and later includes iODBC software as part of the standard systeminstallation. To configure ODBC on OS X systems, use the ODBC Administrator
application in the Utilities folder.

ODBC on Unix systems

Changed lines 3941-3984 from:
the expression button "Edit" refers to that button, not to the one in the menu bar.)
An unambiguous button reference to a menu might look like this:

get line 2 of button "Edit" of group "Menu" of stack "Main"

The above statement produces the same information as the form using "menu", but you
need to know the group name and possibly which stack it's in, so the menu
menuNameform is a little more convenient.

The layer of menu buttons

For a menu bar to work properly on Mac OS and OS X systems, the menus must be in
layer order within the group. That is, the button for the File menu must be numbered 1,
the button for the Edit menu must be 2, and so on. The Menu Builder takes care of thisautomatically; you only need to worry about layering if you're creating the menu bar by
hand.

Changing menus dynamically

If you want to dynamically change a menu's contents with a mouseDown handler at the
time the menu is displayed, you must place the mouseDown handler in the group'sscript. When a menu button is being displayed in the Mac OS menu bar, it does notreceive mouseDown messages, but its group does.

The editMenus property

When you set the menubar property of a stack to the name of a group, the stack isresized and scrolled up so the part of the window that holds the menus is not visible. To
reverse this action so you can see, select and edit the buttons that make up your menu bar,
set the editMenus property to true. This resizes the stack window so the button menusare again visible, and you can use the tools in the LiveCode development environment to
make changes to them.

To scroll the stack window again so that the menus are hidden, set the editMenus
property back to false.

Special menu items

A few menu items on Mac OS and OS X are handled directly by the operating system. To
accommodate these special menu items while allowing you to create a fully crossplatform
menu bar, LiveCode treats the last two menu items of the Help menu (for MacOS and OS X), the File menu (OS X), and the Edit menu (OS X) differently.

By following these guidelines, you can make sure your menus will appear properly on alloperating systems without having to write special code or create platform-specific menu
bars.

The Help menu and the "About This Application" menu item

When LiveCode sets up the Mac OS menu bar, it automatically makes the last button theHelp menu (regardless of the button's name). The standard Help menu items, such as

to:
LiveCode supports iODBC and UnixODBC on Unix systems. You can download theiODBC software from the iODBC web site at http://www.iodbc.org/. You can download
the unixODBC software from the unixODBC web site at http://www.unixodbc.org.

Creating a DSN for ODBC access

Once you have installed the necessary software, you use the ODBC manager to create aDSN, which is a specification that identifies a particular database.

You use the DSN to connect to the database via ODBC. The following example opens aconnection to a database whose DSN is named "myDB":

get revOpenDatabase("ODBC","myDB",,"jones","pass")

To connect to a database using the Database Query Builder, you enter the DSN's name in
the Database Query Builder window.

Note: One of the advantages of setting up a DSN is that if you wish to change thelocation of the database, you only have to edit the DSN settings, not your application
code. You can think of a DSN as a kind of shortcut or alias to your database.
Changed lines 3958-3989 from:
"About This Application" and "Show Balloons" on Mac OS Classic, are included for you
automatically; you don't need to include them in your Help menu button, and you can't
eliminate them from the Help menu.

LiveCode moves the last menu item in the Help menu to the "About This Application"
position. On Mac OS systems, this is the first menu item in the Apple menu. On OS Xsystems, it's the first menu item in the Application menu. Therefore, the last menu item in
your Help menu button should be an appropriate "About" item. The menu item above itmust be a divider line (a dash), and above that must be at least one menu item to beplaced in the Help menu.

The File menu and the "Quit" menu item

On OS X systems, the "Quit" menu item is normally placed in the Application menu
(which is maintained by the operating system) rather than in the File menu, as is standard
on other platforms. To accommodate this user-interface standard, LiveCode removes thelast two menu items of the File menu when a standalone application is running on an OSX system. Therefore, the last menu item in your File menu button should be "Quit". Themenu item above it should be a divider line (a dash).

The Edit menu and the "Preferences" menu item

On OS X systems, the "Preferences" menu item is also normally placed in theApplication menu. To accommodate this user-interface standard, LiveCode removes thelast two menu items of the Edit menu when a standalone application is running on an OSX system. Therefore, the last menu item in your Edit menu button should be"Preferences". The menu item above it should be a divider line (a dash).

Note: The Preferences menu item is treated in this special way only if its name starts
with the string "Preferences".
Tip: If your application's user interface is presented in a language other than English, set
the name of the Edit menu button to "Edit", and set its label to the correct translation.
This ensures that the engine can find the Edit menu, while making sure that the menu is
shown in the correct language.
Choosing the special menu items

When the user chooses any of these special menu items, a menuPick message is sent to
the button that the menu item is contained in. This ensures that your button scripts willwork on all platforms, even if LiveCode displays a menu item in a different menu to
comply with user-interface guidelines.

For example, if the user chooses "About This Application" from the Apple menu on aMac OS system, a menuPick message is sent to the Help menu button, with "About

to:
Printing and Reports

Printing is a vital aspect of many applications. LiveCode provides a comprehensive set ofprinting capabilities. Whether you want a simple print out of your stack, want to printlabels or produce complex reports, LiveCode has the features you need.

Changed lines 3963-4002 from:
This Application" as its parameter. You handle the message for the About menu item in
the Help menu button's script, even though LiveCode displays this menu item in adifferent menu on the Mac.

7.13.7 Stack Menus
Button menus can be used for most kinds of standard menus. However, if you want to
create a menu with a feature that is not supported by button menus--for example, if you
want a popup menu that provides pictures
, rather than text, as the choices--you can createa menu from a stack.

Creating a stack menu

To create
a stack menu, you create a stack with a control for each menu item. Since thestack menu is a stack and each menu item is an object, the menu items receive mousemessages such as mouseEnter,mouseLeave, and mouseUp.

When the user chooses an item from
the stack menu, a mouseUp message is sent to thatcontrol. To respond to a menu item choice, instead of handling the menuPick message,
you can place a mouseUp handler in the script of the object.

To create
a stack menu that looks like a standard menu, create a button in the stack for
each menu item. The button's autoArm and armBorder properties should be set to
true. Or you can choose "Menu Item" item in
the "New Control" submenu of the Objectmenu to create a button with its properties set to the appropriate values.

Be sure to set the rectangle of the stack to the appropriate size for the menu.
Remember, when you open the menu, the stack will be displayed exactly as it looks in an
editable window.

Finally, either set the menuName property of a button to a reference to the stack, or place
a mouseDown handler containing a pulldown, popup, or option command in the
script of an object. When you click
the button or object, the stack menu appears.

Displaying a stack menu

Stack menus can be associated with a button, just like button menus. But when you click
the button, instead
of displaying a menu with the button's contents, LiveCode displays astack with the behavior of a menu.

You can also display a stack menu without associating it with a button, by using thepulldown, popup, or option command. Normally, you use these commands in a

mouseDown handler, so that the menu appears under the mouse pointer:

on mouseDown -- in card script

 popup stack "My Menu Panel"
end mouseDown

to:
8.4 Introduction to Printing
LiveCode supports a number of methods of printing. You can use the print card
command and have LiveCode manage the layout of cards on the paper. Alternatively you
can use the print into rectangle commands which allow you to take full control over thelayout of your print out. The former method is most suited to implementing simple printfunctionality, while the latter is better suited for more complex layout printing or printing
reports. Finally
, you can use the built-in field printing script library to print the contentsof any text field using a simple command.

LiveCode also includes
a full set of features to access and set printer device options,
including options such as margins, page range and number of copies. On Mac OS Xsystems you can also print directly to a PDF file – even without showing
the user a printdialog if choose to. On Windows systems this option will create an XPS file and on Unix
systems a Postscript file. This feature is invaluable if you want to produce a high
resolution file PDF, XPS or Postscript file respectively, from your
stack.

8.5 Controlling Printer Device Settings
LiveCode gives you full programmatic control over your printer device and any availablesettings.

8.5.1 Choosing a Printer
Use
the availablePrinters to list the printers available on the user's system.
Printers can include fax modems and networked devices. If the availablePrinters
is empty, no printer is assigned. For example, to place a list of the available printers into alist field:

put the availablePrinters into field "list of printers"

Set the printerName to the printer you want to use to print. You can use any printer
listed in the availablePrinters. This property is useful when producing an inhouse
utility that needs to print to a specific printer on
the corporate network, or for
automatically restoring the user's previous printer choice stored in a preferences file.

set the printerName to the cSavedPrinter of stack \
"My Preferences"

The printerFeatures provides a list
of the features supported by the currently
selected printer. Features will vary widely from device to device, but typical features may
include things such as "collate", "color" and "duplex". Use this property to enable and
disable output options in any custom printer settings dialog.


8.5.2 Choosing Output Mode (e.g. Print to File)
The printerOutput global property allows you to choose the output mode for
subsequent printing commands. This property is set by the system to the default printer

Changed lines 4002-4042 from:
7.13.8 Displaying Context Sensitive Menus
There are also several commands to display a context menu. Usually, you use thesecommands in
a mouseDown handler – normally either in your card or stack script:

popup command: opens a stack as a popup menu
pulldown command: opens
a stack as a pulldown menu
option command: opens a stack as an option menu


Note: If you set a button's menuName property to the name of a stack, the stack menu
is displayed automatically when the user clicks the button
. You need the popup,
pulldown, and option commands only if you want to display a stack menu in some way

other than when a button is clicked. 
7.14Searching and Navigating Cards using the Find Command

The find command in LiveCode allows you
to search the fields of the current stack, then
navigate to
and highlight the results of the search automatically. While it is possible to
build such a command using
the comparison features detailed in the chapter Processing
Text and Data, for most purposes
the find command provides a complete, pre-built
solution.

find [form] textToFind [in field]

The form can be one of the following:
normal
characters or character (or chars or char)
words or word
stringwhole

If no form is specified,
the find normal form is used.

The textToFind is any expression that evaluates to a string.

The field is any expression that evaluates to a field reference. If
the field is not specified,
the find command searches all the fields in the current stack (except fields whosedontSearch property is set to true).

find "heart"
find string "beat must go on" in field "Quotes"


When
the find command finds a match, it highlights the match on the screen – ifnecessary navigating to the card that contains the match and scrolling the field so the textis in view.
to:
on startup and will be changed if you open a system print dialog in which the user
chooses
a different printer. If this property is set to device it will output to the physicalprinter. Alternatively, you can set it to a file path to print to a file. On Mac OS X this willcreate a PDF file, on Windows an XPS file and on UNIX a postscript file. On Mac OS Xyou can set this to preview to create a preview.

For example, to save the current card to a file:

ask file "Save as:
set the printerOutput to ("file:" & it )
print this card

8
.5.3 Working with Printer Dialogs
In most applications that need to print, you will want
to provide a way to bring up thestandard OS Print and Page Setup dialogs. Typically you would make these dialogsavailable from Print and Page Setup items in the File menu of your application. When theuser makes changes in these dialogs the changes are made accessible to you in globalproperties. We discuss how to save and utilize these properties below.

Note: It is not necessary to bring up the standard OS dialogs to alter printer settings.
You may set
the appropriate printer setting directly by script instead.
Note: On Linux & Unix systems you will need a recent version of GTK installed in
order to display
the OS printer dialog. If you don't have this installed, LiveCode will
display its own printer dialog which has been built as a stack and script library. Thisdialog mimics the standard system printer dialog and sets
the LiveCode printing globalproperties directly.
Tip: You may force LiveCode to use its own internal print settings dialog by setting
the
systemPrintSelector global property to false. Advanced users may customize
the printer dialog that LiveCode uses by running toplevel "print dialog"or
toplevel "page setup" in the Message Box. Remember to save a copy of the
stack as it will be overwritten each time you upgrade your copy of LiveCode.
Important: The LiveCode print and page setup dialogs must be included in a standaloneapplication if you use them. Ensure that the check box Print Dialog is turned on in the
Changed lines 4026-4062 from:
The find command can also be used to return the location of the text that was found.
To reset
the find command so that it starts searching at the beginning again:

find empty

For more details
on the find command and associated options, see the find command in
the LiveCode Dictionary.

7.15Using Drag and Drop

LiveCode allows you complete control over drag and drop – both within LiveCodewindows and between LiveCode and other applications.

7.15.1 Initiating a Drag Drop
To begin a drag and drop operation,
the user clicks and holds the mouse pointer. Thissends a mouseDown message to the object. 

If you drag from within
a field, a dragStart message is sent. To allow drags from alocked field or from another object type, in the object's mouseDown handler, set the
dragData property to the data you want to drag. When there is a value in the
dragData, a drag
and drop is initiated when the mouse is clicked and then moved.

set
the dragData["text"] to "text being dragged"

You can set the dragData to contain any of
the following types of data:

text The plain text being dragged.
HTML The styled text being dragged
, in the same format asthe htmlText
RTF The styled text being dragged, in the same format asthe RTFText
Unicode The text being dragged, in the same format as
the
unicodeText

image The data of an image (in PNG format)
files The name and location of the file or files being
dragged, one per line

Note: LiveCode automatically handles the mechanics of dragging and dropping text
between and within unlocked fields. To support this type of drag and drop operation, you
don't need to do any scripting.
For more details, see the entries for dragStart and dragData in the LiveCode Dictionary.

to:
Standalone Application Settings dialog for your application. You do not need to include
these dialogs if you only use
the OS native print dialogs. For more information on
including resources in your standalone application, see the chapter
on Building
Standalone Applications.
To bring up
the standard OS printer dialog, use the answer printer command.

answer printer

If the user does not press the cancel button then any changes to the printer settings will bereflected in the global printing properties, discussed below.

To bring up
the standard OS page setup dialog, use the answer page setupcommand.

answer page setup

8
.5.4 Saving Printer Settings
To save or set
a complete set of options relating to the current printer which includesevery setting in the OS Page Setup and Print dialogs, use the printerSettingsglobal property.

The printerSettings
property is a binary string that completely describes thecurrent settings. The property contains the name of the printer and the settings currently
in use.

Caution: You should not attempt to modify
the printerSettings but rather get and set itin its entirety. To access individual printer properties, use the global printing properties
described below.
When you set the printerSettings property to a saved value
, LiveCode will choosethe printer named in the property and set all of its settings to those contained within theproperty. If the printer cannot be found LiveCode will return the error "unknown printer"
in the result. If the printer is found but the settings are not valid then LiveCode willchoose the printer and reset it to default values.

Note: You must save a separate copy of the printerSettings property for each printer orOS you intend to use. The printerSettings property cannot be transferred between
platforms. For example, a printerSettings property generated on a Windows computer
cannot be used on Mac OS X – even for the same printer. If you want to alter settings
across different platforms and printer types use the global printing properties described
below. Use the printerSettings for convenience when you know you will be using the
Changed lines 4057-4099 from:
7.15.2 Tracking During a Drag Drop Operation
You can use the dragEnter message to show an outline around an object or change thecursor when the mouse moves into it during a drag operation.

on dragEnter -- show a green outline around
the drop targetset the borderColor of the target to "green"
end dragEnter

You can use the dragMove message
to update the screen whenever the cursor movesduring a drag and drop operation.

on dragMove -- in a field script

-- set
the cursor so it shows you can only drop onto a linkif the textStyle of the mouseChunk contains "link"
then set the cursor to the ID of image "Drop Here"
else set the cursor to the ID of image "Dont Drop"

end dragMove

You can use the dragLeave message to remove any outline around an object or changethe cursor when the mouse moves out of an object during a drag operation.

on dragLeave
-- remove any outline around the drop no-longer-targetset the borderColor of the target to empty

end dragLeave

For more details, see
the entries for dragEnter, dragMove and dragLeave in the LiveCode
Dictionary
.

7.15.3 Responding to a Drag and Drop
To perform an action when
the user drops data onto a locked field or another object type,
you handle the dragDrop message.

The dragDrop message is sent when the user drops data on an object.

on dragDrop -- check whether a file is being dropped
if the dragData["files"] is empty then beep 2pass dragDrop

end dragDrop

You must set the acceptDrop property
to true before a drop will be allowed. Usually,
you set this property to true in a dragEnter handler.

You can use the dragDestination function to retrieve the long id of the object thatthe dragged data was dropped on. You can use the dragSource function to retrieve the
long id of the object that was the source of the drag.

to:
same printer and want to save all the settings, or where you are setting esoteric propertiesnot listed in the global printing properties described below.
To save the current printer settings into a custom property stored on the current stack:

set
the cSavedPrinterSettings of this stack to \

the printerSettingssave this stack

Then to restore these settings:

set the printerSettings
to the cSavedPrinterSettings \
of this stack

8.6 Paper Related Options
This section discusses how you get and set paper related options –
the rectangle area ofthe paper, the paper size, the orientation and the scale to use to print onto the paper.
These paper options apply to all types of printing, i.e. card, field and layout printing.

Use the printRectangle to get the printable rectangle area within the paper (returned
in device co-ordinates). This property takes into account any settings applied by the user
in the Page Setup and Printer dialogs including the print orientation (e.g. landscape or
portrait). The rectangle is represented left,top,right,bottom and is always relative to thetop left of
the page – thus the top left will always be 0,0. The printRectangle will alwaysbe within the printPaperRectangle– the rectangular area of the sheet of paper.

Note: The printRectangle property is read only and cannot be set directly – to
alter it you must set other options relating to the paper, for example the

printPaperOrientation (discussed below).
Important: Do not confuse the printMarginsand other card layout printingproperties with paper properties such as the printRectangle. The
printMargins only applies
to printing cards using LiveCode's automatic cardlayout capabilities (discussed below). Thus the printMargins has no effect on
printRectangle.
Use the printPaperOrientation to get and set the orientation of your print out.
This property may be set to one of the following values:


portrait: rotated 0 degrees.
landscape: rotated 90 degrees clockwise.


Changed lines 4093-4128 from:
When a drag drop has been completed, a dragEnd message is sent to the object the drag
and drop started from.

on dragEnd -- remove data being dragged

delete the dragSourceend dragEnd

You can use the dropChunk function to retrieve the location of the text that was
dropped in a field. For example, you could select the text that was dropped by doing thefollowing:

select the dropChunk

For more details
, see the entries for dragDrop, dragEnter, dragDestination, dragEnd,
dragSource , dropChunk and acceptDrop in the LiveCode Dictionary.

7.15.4 Prevent Dragging and Dropping to a Field
You prevent dropping data into
a field during a drag and drop by setting theacceptDrop property to false when the mouse pointer enters the field.

If the acceptDrop is set to false, when you drop data, no dragDrop message is sentto the field. Since
the drop is automatically processed only when LiveCode receives adragDrop message, this prevents the usual automatic drop behavior.

Usually, you should set
the acceptDrop in a dragEnter handler, as in the following
example:

on dragEnter -- in a field script

 set the acceptDrop to falseend dragEnter

If you want to prevent dragging text within a field, intercept the dragStart message:

on dragStart

-- do nothingend dragStart

For
more details, see the entries for acceptDrop, dragDrop and dragEnter in the
LiveCode Dictionary.

to:
reverse portrait: rotated 180 degrees clockwise.
reverse landscape: 270 degrees clockwise.

set the printPaperOrientation
to "landscape"

Use
the printPaperScale property to apply a scale factor to your print out after allother settings have been taking into account.

Note: The printPaperScale is applied after all other layout and scaling options.
For example, if you have used the layout printing features to print a series of cards at50% scale, then set the printPaperScale
, this factor will be applied to the entire
layout after the card layout scaling has been calculated.
To print a range between 1 and 100% set the printPaperScale to a number between
0
and 1. To print at 200% set the printPaperScale to 2.

set
the printPaperScale to 0.5 -- 50%

8.7 Job Related Options
This section discusses how to get and set job related options –
the number of copies,
duplex printing, collation, color, title and printable area.

Important: The available job options all depend on what
the currently selected printer
supports (use the printerFeaturesproperty, described above, to retrieve a list offeatures supported by the current printer).
Use the printCopies property to get and set the number of copies to print. TheprintCopies should be set to a value of 1 or
more.

set
the printCopies to 5 -- print 5 copies

Use
the printDuplex property to tell the printer to print double sided. This property
may be set to any of the following values:


none: no double-sided printing
short edge: double-sided printing with tumble (flip the non-facing page)
long edge: double-sided printing without tumble.


set the printDuplex to "short edge"

Use the printCollate property to specify whether to interleave multiple copies of aprint job. If a print job has three pages, P1, P2 and P3, with printCollate set to true

Changed lines 4132-4152 from:
Chapter 8 Working With Databases

With
the LiveCode Database library, your application can communicate with externalSQL databases. (Database access is not available in LiveCode Media.) You can get datafrom single-user and multi-user databases, update data in them, get information about thedatabase structure, and display data from the database in your stack. And with theDatabase Query Builder, you can automate the process of querying a database and
populating fields with the data, with no scripting required. For a discussion of when it isappropriate
to use an external database with LiveCode, see the topic When to Use aDatabase in Chapter 2.

This chapter discusses how to install necessary software to communicate with databases,
how to set up automatic database queries using
the Database Query Builder, and how to
use
the Database library to communicate between LiveCode and a database.

This topic does not include discussion
of how to set up and create a SQL database, which
is beyond
the scope of the LiveCode documentation.

To fully understand this topic, you should know how to write short scripts and should
understand the basic concepts of SQL databases (rows and columns, database cursors,
and SQL queries).

A few terms used in this topic, such
as "field" and "cursor", are part of the standard
terminology for working with databases, but have a different meaning in
the context ofLiveCode development. When going back and forth between database work and moregeneral application development, be sure you understand which meaning is applicable in
the context you're currently working in. When referring to database-specific terms, thedocumentation usually uses phrases like "database field" or "database cursor" to remind
you of the context. See the Glossary within the product documentation for definitions ofany term you are unsure of
.
to:
and printCopies set to 2 the output order will be P1, P2, P3, P1, P2, P3. With
printCollate set to false the output will be P1, P1, P2, P2, P3, P3.

set the printCollate to true

Use the printColors property to specify whether to print in color or not
. If "color" isnot among the lines of the printerFeatures then this property will have no effectand all print jobs will be printed in monochrome. This property may be set to either true
or false.

For example
, to check if color printing is supported on the current printer and use it if itis:

if "color" is among the lines of the printerFeatures thenset the printColors to true

Use
the printTitle property to specify the name of the next print job in the systemprinter queue. Setting this property to match the name of the user's document will ensurethat the user is able to recognize it in the system printer queue utility. If theprintTitle is empty at the start of a printing loop, the title of the defaultStack
will be used.

set the printTitle to "My Report 1"

Use the printRectangle property to determine the printable region of the physicalpage
as returned by the printer. This rectangle will always be contained within theprintPaperRectangle. Thus you should use the printRectangle and not the
printPaperRectangle when calculating a print layout. The
printPaperRectangle is useful if you are generating a print preview and want to
show the entire area of the paper including any margin areas that cannot be printed on.
This property is read only and cannot be set directly.

8.7.1 Printer Font Metrics (Windows)
Windows systems sometimes use different versions of the same font for displaying texton screen and printing. This can result in layouts and line breaks differing between thescreen display and the printed output. To prevent this from happening, you can tellLiveCode to use the printer fonts for display on screen. To do this, set a stacksformatForPrinting property to true.

Do:

Don't:

Set the formatForPrinting stack Allow the user to directly edit text in fields
property to true before loading a stack in whose formatForPrinting is set to
memory. If the stack is already loaded, true. Attempting to do this may causeset this property to true then save and display anomalies. Set this property to falsereload it. (Save then use Close and and reload the stack first
.
Changed lines 4167-4170 from:
8.1 Introduction to Database Access
A database is an external resource that holds information, structured in a special form for
quick access and retrieval. Databases can be:

to:
Remove from Memory in the File menu). in the File menu).

Generally use stacks with
Create a stack off screen (with formatForPrinting set to true for
formatForPrinting set to true) display on screen, as this will show text that
with your print layout template and copy has been optimized for print display (instead
text into it prior to printing. of screen display), which is harder to read

on screen.
Set the formatForPrinting before
doing any print layout related Use this property on other platforms –
calculations on the stack. Windows is the only platform that uses

different fonts on screen vs. in a print out.
Set the formatForPrinting to true
on any print preview stack being Use the windowBoundingRectdisplayed to the user. property to constrain display of a stack

who's formatForPrinting has been set
to true – this property will be ignored when
the stack is opened or maximized.

Figure 59 – Dos and don'ts of printer font metrics on Windows

8.8 Printing a Card
Once you have set your printer, paper and job options (above) you are now ready to useone of the print commands to start printing. At its simplest, the print card command
allows you to print a card. Later we will discuss ways of printing more complex layouts,
fields and text.

print this card -- prints the current cardprint card 12 -- prints card 12

For more details on how to specify which cards to print, see the print command in the
LiveCode Dictionary.

To print a scale between 1 and 100% set the printScale to a number between 0 and 1.
To print at 200% set the printScale to 2.

Important: The printScaleapplies to each card that you print. It is not related tothe printPaperScale which is applied to the entire print job after all other scaling
calculations have been applied. Thus you may set the printPaperScaleto 0.5 to
print at 50%, then print individual cards at different printScale values. With a
printPaperScale of 0.5, a printScale of 2 would result in that card being
printed at 100%.
When printing a card, use the printMargins to specify the margins around the border
of the card on the page.

 
Note: When calculating placement on the printed page, all calculations assume thatthere are 72 dots per inch – regardless of platform or printer device. LiveCode will
automatically adjust the print out for resolution of the actual device. This makes it simple
to calculate your printed layout.
-- a one-inch margin on each sideset the printMargins is set to 72,72,72,72

Important: printMargins only applies when using print card directly. It does not
have any effect on printing cards into a layout (described below).
The printCardBorders property specifies whether or not the bevel border around
the edge of a card should appear in the print out.

8.8.1 Card Layout Options
When using the basic print card form of the print command, there are two layout optionsthat allow you to customize the positioning of cards on the printed page. If you requirefurther flexibility, see the section on printing a layout, below.

Use the printRowsFirst property to specify whether cards should be printed acrossand down or down then across.

Consider a simple example of printing multiple cards – this example is useful for printing
labels. In this example we have a stack that contains 8 cards, each one containing amailing label. If you want to try out this example:

Changed line 4231 from:
any size from small to extremely large
to:
Create a stack and size it to be small – the size of a mailing label
Changed line 4233 from:
located on the same system as the application or on a remote server
to:
Create a single field, and in the field Inspector turn off the Shared Text property
Changed lines 4235-4263 from:
accessible by one user at a time or by many users at once
8.1.1 SQL Databases
A SQL database is a database that you access and control using SQL, a standard
database-access language which is widely supported. You use SQL queries (statements in

the SQL language) to specify the part of the database you want to work with, to get data,
or to make changes to the database.

LiveCode's database access is fully-featured. You can send any SQL statement to adatabase. You can open multiple databases (or multiple connections to the samedatabase), maintain multiple record sets (database cursors) per connection, and send and
receive binary data as well as text. You can do all this using the Database Query Builder,
or in scripts that use the commands and functions in the Database library.

To see a list of LiveCode terms in the Database library, open the Dictionary, and type
"database" into the search filter field. You can also find a interactive workshop and
tutorial materials on our web site at:

http://www.runrev.com/developers/lessons-and-tutorials/explore-livecode/databases/

8.1.2 Why use an External Database?
See the section on When to use a Database in Chapter 2.

8.1.3 The Basics of Database Structure
A database is built of records, which in turn are built out of database fields. A field is thesmallest part of a database that can be separately addressed. Each database field containsa particular kind of information. This might be a name, a file path, a picture, or any other
kind of information. Each record contains one value for each of its fields. A set of records
is called a database table, and one or more tables comprise a database.

Here's an example: suppose you have a database of customers for your business. Thefields of this database might include the customer name, a unique customer ID number,
and shipping address. Each record consists of the information for a single customer, so
each record has a different customer name, shipping address, and so on
.
to:
Group the field and in the group property Inspector turn on Behave as
Background
*
Turn on Select Grouped on the Toolbar and select the field
*
Place the contents of the first mailing label into the Contents tab of the Inspector
*

Create 8 more cards, and in each select the field and place the contents of adifferent label
Thus we have a stack that looks like the figure below.

Changed lines 4246-4285 from:
Note: You may have noticed that the database structure being described resembles amultiple-card stack that has the same fields on each card. A database field is like a field
in a stack, and a record is like a card. A stack set up this way can act as a database, in
fact, but lacks some of the features of an external database, such as the ability to performSQL queries and the ability to perform robustly when accessed by more than one user.
You can also think of the set of customer records as a grid (like a spreadsheet). Each rowis a record, and each column is a field, so each cell in the grid contains a different pieceof information about a particular customer. Here's an example:

ID

Customer Name

Address

Country
123 Jane Jones 234 E. Street U.K.
836 Acme Corporation PO Box 23788 USA
823 CanCo, Inc. 1 CanCo Blvd. Japan

Figure 58 – Example Database Grid

There are three rows in this grid (each is the record for a particular customer) and four
columns (each is one of the fields).

A row of the database means one single customer record, which has one value for each
field. A column of the database means the set of all values for one of the fields, one for
each record (for example, the set of all customer addresses).

More generally, each row describes one of the things in the database, and each column
describes a particular state for each thing in the database.

The set of all customer records makes a table. Your database might include only thistable, or it might include other related tables, such as a list of all sales. You can also
connect related data from different tables of the same database. For example, if each
record in the Sales table includes the ID number of the customer who bought the product,
you can link all the sales records for a customer to that customer's record in theCustomers table.

8.1.4 SQL and Record Sets – Database Cursors
SQL works primarily with sets of records, rather than individual rows. When you send aSQL query to a database, the query typically selects certain records which you can
perform further operations on. The set of records resulting from a SQL query is called adatabase cursor, or record set. SQL queries let you describe the characteristics of therecords you require, instead of processing each record one by one to find out whether itmatches your criteria.

For example, consider the customer table we talked about in the previous section. To
work with only US customers, you can write a SQL query that selects only records wherethe country field is "USA". This subset of records then becomes a record set. You can

to:
Figure 60 – Print label stack example

Now we will implement the printing commands. If this was a real application you would
probably want to put these in a Print command in the File menu. In this instance you may
execute the following in the multi-line message box (open the Message Box then pressthe second icon to get the multi-line pane).

-- allow the user to choose printer output optionsanswer printerprint 9 cards

Press enter to execute the commands.

The resulting print out will look like the figure below.


Figure 61 – Printing 9 label-sized cards with default settings

Changed lines 4262-4287 from:
find out more about the fields and records contained in this record set, and move fromrecord to record within this subset of the database. You can create more than one record
set to work with more than one set of records at a time.

Note: Different database implementations have different limitations on movementwithin a record set. For example, some databases won't let you move backward within a
record set: instead, you must start at the first record and move forward in order to
examine
the data.
8.1.5 Choosing a Database
LiveCode directly supports the following database implementations:
Oracle
MySQLSQLitePostgreSQLValentina

LiveCode also supports connecting to a database via ODBC. You can use ODBC to useAccess, FileMaker, MS SQL Server and many other database implementations. Seebelow for more information about ODBC.

LiveCode's database commands and functions use the same syntax regardless of whattype of database you are connecting to. You don't need to learn a separate databaselanguage for each type. Instead, when you first open a database with therevOpenDatabase function, you specify the type as one of the parameters so LiveCodeknows what type of database it's dealing with. The Database library handles the details ofeach type behind the scenes for you.

When you use the Database Query Builder, you simply select the database type you want
to use. Like the Database library, the Database Query Builder handles the details for you.
You can easily switch between database types.

8.2 Reasons to Choose a Database Type
Which type of database to choose depends on a number of factors. If you need to work
with an existing database, or already have a database manager installed, the decision ismade for you. Likewise, if you're already an expert at a particular databaseimplementation, you'll probably prefer to go on using that one.

Other factors in your choice may include price, performance, licensing model(commercial or open source), and platform support. If your users are on a particular set ofplatforms, you'll need to choose a database that is supported on all those platforms.
Runtime do not endorse any particular database type, the information provided on thedifferent types is for informational purposes only.

to:
If we modify the print commands to include an additional line to turn off theprintRowsFirst:

answer printerset the printRowsFirst to falseprint 9 cards

The resulting print out will look like the figure below.


Figure 62 – Printing 9 label-sized cards with printRowsFirst set to false

Use the printGutters property to specify the margin between each card. By defaultthe printGutters are set to 36,36 or one half inch horizontally and vertically.

In the following example, we print the same label stack but reduce
the space between
each label to 1/10th of an inch. To make it easy to see the differente we also turn on
printing of card borders using the printCardBorders property.

answer printerset the printGutters to 7,7set the printCardBorders to true

Changed lines 4280-4315 from:
8.2.1 Overview of ODBC
Open Database Connectivity (ODBC) is a system that allows developers to access any
type of compatible database in a standard way.

To communicate with a database, you usually have to add code that uses the database's
own proprietary protocols. Without ODBC, in order to create a program that can
communicate with--for example--FileMaker, Access, and Oracle databases, LiveCodewould have to include code for three different database protocols. With ODBC, LiveCodecan communicate with any of these database types using the same code.

ODBC Managers

To work with databases through ODBC, you need two pieces of software: an ODBC
manager, plus a database driver for the specific database type you're using.

Windows 2000 and Windows XP, and OS X version 10.2 and later, include ODBC
software with the operating system. For earlier versions, and for Mac OS and Unix
systems, you can download an ODBC manager and a set of drivers. (See the section
below titled "Software for Database Access" for more information.)

8.2.2 Performance for Direct Access Versus ODBC Access
Typically, accessing a database via ODBC takes more configuration and is slower than
accessing the database directly. For this reason, LiveCode provides the ability to accessMySQL, PostgreSQL and Oracle databases directly without going through the ODBC
protocol. This ability will be valuable for anyone doing complex or extensiveprofessional database work.

The syntax of the functions in the Database library is identical for all database types, so
you do not need to rewrite your scripts to take advantage of the increased efficiency ofdirect access.

8.3 Software for Database Access
To provide connectivity to databases, LiveCode works with database drivers--softwarethat translates application requests into the protocol required by a specific database.

8.3.1 Finding Database Drivers
Database drivers for certain database types are included in the LiveCode distribution.
(The list of included database types depends on the platform.) The sections below listwhich database drivers are included with which platforms.

If you have installed LiveCode, you have all the software needed to use the included
database types. For other database types, you will need to obtain the appropriate databasedrivers before you can work with those databases.

to:
print 9 cards

The resulting print out will look like the figure below.
Figure 63 – Printing 9 label-sized cards with borders and a narrow gutter betweeneach
8.9 Printing Fields & Text
To print a field, use the revPrintField command. This command takes a singleparameter, a reference to a field. This command only allows printing a single field. If you
need to include a header and footer or text you have constructed programmatically, seethe revPrintText command below.

revPrintField the long id of field "text document"

Tip: revPrintFieldis implemented as a script library located in the LiveCodeIDE. The script library creates an invisible stack, sets the rectangle of that stack to the
current paper size, sets the formatForPrinting to true, creates a field, then copies
the contents of the field you specify into this invisible stack. It then prints the field one
page at a time, scrolling the text after each page. Advanced users can locate this library
script by going to the Back Scripts tab in the Message Box, turning on the checkbox for
Changed lines 4296-4334 from:
Important: This section includes links to third-party web sites and contains information
about third-party software. This information is provided for your convenience, but
RunRev is not responsible for
the software packages and sites referenced. Runtime
regrets that it cannot provide any support for installation and configuration of any
databasae.
8.3.2 MySQL
MySQL database drivers are included as part
of the LiveCode installation on Linux, MacOS X, and Windows systems.

8.3.3 Oracle
LiveCode includes drivers for Oracle on Windows
and (currently) PPC Mac OS X.

To obtain an Oracle database driver for your platform, visit the Oracle web site athttp://www.oracle.com.

8.3.4 PostgreSQL
A PostgreSQL database driver is included as part of the LiveCode installation on Linux,
Mac OS X and Windows systems
.

8.3.5 SQLite
Drivers for accessing this database are included with LiveCode. No additional installation
is necessary.


8.3.6 ODBC managers and database drivers
To use a database via ODBC, you must install the necessary ODBC software for your
platform. (Some operating systems include an ODBC installation.) ODBC softwareincludes one or more database drivers, plus an ODBC manager utility.

ODBC on Windows systems

Windows 2000 and Windows XP include the MDAC (Microsoft Data AccessComponents) package as part of
the standard system installation. To configure ODBC on
Windows systems, use the ODBC Data Sources control panel.

For earlier versions of Windows, you can download MDAC from the Microsoft web siteat http://www.microsoft.com/data/download.htm.

ODBC on Mac OS X systems

OS X version 10.2 and later includes iODBC software as part of the standard systeminstallation. To configure ODBC on OS X systems, use the ODBC Administrator
application in the Utilities folder.

ODBC on Unix systems

to:
Show LiveCode UI Back Scripts, then editing the script of button "revPrintBack". The
revPrintField handler is near the top of the script.
Use the revShowPrintDialog command to control whether
the system printer and
page setups dialogs should be shown by revPrintFieldor revPrintText.

-- show the system printer dialog, but not page setuprevShowPrintDialog true, falserevPrintField the long id
of field "text document"

Use the revPrintText command to print plain or styled text together with an optional
header
and footer.

revPrintText textToPrint [,headerText [,footerText[,fieldTemplate]]]


The textToPrint is anything which evaluates to a string. If you want to printed styled text,
pass HTML instead of plain text. (To convert a field containing styled text to a HTMLuse the htmlText property
.)

The headerText and footerText contains the text to use as a header and footer. You may
include an expression that is computed for each page. For more details on using
expressions, see the LiveCode Dictionary entry for revPrintText.

The fieldTemplate parameter allows you to specify a field reference to use. Fonts in theprint out will be inherited from this field.

8.10Printing a Layout

If you need to print a more complex layout than allowed with
the basic print card
command or text printing commands (described above), you can use the print cardinto rect syntax to create any sort of layout you choose.

print card from topLeft to rightBottom into pageRect

The topLeft is the top left coordinate of the current card to start printing at.

The rightBottom is the bottom right coordinate of the current card to stop printing at.

The pageRect is the rectangular area on the paper to print into.

Important: printMarginsonly applies when using print card directly. It does nothave any effect on printing cards into a layout. Use the printRectangleto get theprintable area when working with layout printing.
Changed lines 4332-4347 from:
LiveCode supports iODBC and UnixODBC on Unix systems. You can download theiODBC software from the iODBC web site at http://www.iodbc.org/. You can download
the unixODBC software from the unixODBC web site at http://www.unixodbc.org.

Creating a DSN for ODBC access

Once you have installed the necessary software, you use the ODBC manager to create aDSN, which is a specification that identifies a particular database.

You use the DSN
to connect to the database via ODBC. The following example opens aconnection to a database whose DSN is named "myDB":

get revOpenDatabase("ODBC"
,"myDB",,"jones","pass")

To connect to a database using the Database Query Builder, you enter the DSN's name
in
the Database Query Builder window.

Note: One of the advantages of setting up a DSN is that if you wish to change thelocation of the database, you only have to edit the DSN settings, not your application
code. You can think of a DSN as a kind of shortcut or alias to your database.
to:
For example, lets say that we want to print the text field from the middle of the stack in
figure 73 below
. (You can load the stack shown in the picture by going to your LiveCodeinstallation folder then opening Resources-> Examples-> SQLite Sampler.rev.) We wantthe output to scale to take up the entire width of the paper and half the height.


Figure 64 – Stack with text field
to print into a layout

print this card from the topleft of field "theText" \
to the bottomRight of field
"theText" into \
0
,0,item 3 of the printRectangle, \
round(item 4 of the printRectangle / 2)

This results in the print out shown
in figure 74 below.
Changed lines 4346-4349 from:
Printing and Reports

Printing is a vital aspect of many applications. LiveCode provides
a comprehensive set ofprinting capabilities. Whether you want a simple print out of your stack, want to printlabels or produce complex reports, LiveCode has the features you need.
to:
Figure 65 – Result of layout printing command

You can construct
a complex layout taking components from multiple stacks by printing
a sequence
of rectangles onto the same page. For example, you may have a stack thatcontains a standard header and footer, another that contains a logo, and a layout thatcontains text. Use the open printing command to start a print job, then print each
element into the appropriate rectangle on the paper. The use then close printingcommand to send the print job to the printer. The example in figure 75 below shows two
stacks with printable regions that we want to combine onto a single sheet of paper.


Changed lines 4355-4392 from:
8.4 Introduction to Printing
LiveCode supports a number of methods of printing. You can use the
print card
command and have LiveCode manage the layout of cards on the paper. Alternatively you
can use the
print into rectangle commands which allow you to take full control over thelayout of your print out. The former method is most suited to implementing simple printfunctionality, while the latter is better suited for more complex layout printing or printing
reports. Finally, you can use the built-in field printing script library to print
the contentsof any text field using a simple command.

LiveCode also includes a full set of features to access and set printer device options,
including options such as margins, page range and number of copies. On Mac OS Xsystems you can also print directly to a PDF file – even without showing the user a printdialog if choose
to. On Windows systems this option will create an XPS file and on Unix
systems a Postscript file. This feature is invaluable if you want to produce
a high
resolution file PDF, XPS or Postscript file respectively, from your stack.

8.5 Controlling Printer Device Settings
LiveCode gives you full programmatic control over your printer device and any availablesettings.

8.5.1 Choosing a Printer
Use the availablePrinters to list the printers available on the user's system.
Printers can include fax modems and networked devices. If the availablePrinters
is empty, no printer is assigned. For example, to place a list of the available printers into alist field:

put the availablePrinters into field "list of printers"

Set the printerName to the printer you want to use to print. You can use any printer
listed in the availablePrinters. This property is useful when producing an inhouse
utility that needs to print to a specific printer on the corporate network, or for
automatically restoring the user's previous printer choice stored in a preferences file.

set the printerName to the cSavedPrinter of stack \
"My Preferences"

The printerFeatures provides a list of the features supported by the currently
selected printer. Features will vary widely from device to device, but typical features may
include things such as "collate", "color" and "duplex". Use this property to enable and
disable output options in any custom printer settings dialog.

8.5.2 Choosing Output Mode (e.g. Print to File)
The printerOutput global property allows you to choose the output mode for
subsequent printing commands. This property is set by the system to the default printer

to:
Figure 66 – Separate header and body stacks to print into a layout

To
print these onto a single sheet:

answer printer -- show the system print settings dialog
open printing -- start a
print job-- work with the header stack

set the defaultStack to "header"

-- print the header field onto the top left of the paper

print this card from
the topLeft of field "header" \
to the bottomRight of field "header" into \
the rect of field "header"

-- save the bottom of
the header

put the bottom of field "header" into tHeaderBottom
set the defaultStack to "report editor"

-- print the table field below the header

print this card from the topleft of field "report table" \
to the bottomRight of field "report table" into \
0,tHeaderBottom,the right of field "report table", \
the bottom of field "report table" + tHeaderBottom

-- send the job
to the printer

close printing


Figure 67 – Result of layout printing command with multiple stacks

8.10.1 Printing a complex layout
To print a more complicated layout, create
a stack and set its rectangle to the currentprintRectangle. Add rectangular areas for each component you will be printing.
Changed lines 4393-4415 from:
on startup and will be changed if you open a system print dialog in which the user
chooses a different printer. If this property is set to device it will output to the physicalprinter. Alternatively,
you can set it to a file path to print to a file. On Mac OS X this willcreate a PDF file, on Windows an XPS file and on UNIX a postscript file. On Mac OS Xyou can set this to preview to create a preview.

For example, to save the current card to a file:

ask file "Save as:
set
the printerOutput to ("file:" & it )
print this card

8.5.3 Working with Printer Dialogs
In most applications that need to print, you will want to provide a way to bring up thestandard OS Print and Page Setup dialogs. Typically you would make these dialogsavailable from Print and Page Setup items in the File menu of your application. When theuser makes changes in these dialogs
the changes are made accessible to you in globalproperties. We discuss how to save and utilize these properties below.

Note: It is not necessary
to bring up the standard OS dialogs to alter printer settings.
You may
set the appropriate printer setting directly by script instead.
Note: On Linux & Unix systems you will need a recent version of GTK installed in
order to display the OS printer dialog. If you don't have this installed, LiveCode will
display its own printer dialog which has been built as a stack and script library. Thisdialog mimics the standard system printer dialog and sets the LiveCode printing globalproperties directly.
Tip: You may force LiveCode to use its own internal print settings dialog by setting the
systemPrintSelector global property to false. Advanced users may customize
the printer dialog that LiveCode uses by running toplevel "print dialog"or
toplevel "page setup" in the Message Box. Remember to save a copy of the
stack as it will be overwritten each time you upgrade your copy of LiveCode.
Important: The LiveCode print and page setup dialogs must be included in a standaloneapplication if you use them. Ensure that the check box Print Dialog is turned on in the
to:
Then set Geometry properties (see the section on the Geometry Manager, above for moreinformation) on each of these rectangles so they resize correctly when the stack is scaled.
Set up your print routine so that
you open this stack invisibly then resize it to theprintRectangle. This will trigger the geometry routines and scale the rectangular
areas correctly. Then run your sequence of print commands to print into each rectangle.

In figure 77 below, we have set the size of the stack to the printRectangle then
added 4 rectangle graphics. We have named each graphic and turned on
the Show Name
property for each so you can see the name.


Figure 68 – Stack template for printing a layout

Next, we set Geometry properties for each of the rectangle graphics. The header graphicis set to scale relative to the right and bottom, with a minimum size limit of 100 pixels(see figure 75 below). The body graphic is set to link
the top edge to the header graphic,
the right and bottom
to the stack (see figure x below). The footer 1 graphic is set to scalethe right edge and position the bottom edge. And footer 2 is set to position both the rightand bottom.
Changed lines 4408-4437 from:
Standalone Application Settings dialog for your application. You do not need to include
these dialogs if you only use
the OS native print dialogs. For more information on
including resources in your standalone application, see
the chapter on Building
Standalone Applications.

To bring up the standard OS printer dialog, use the answer printer command.

answer printer

If the user does not press
the cancel button then any changes to the printer settings will bereflected in the global printing properties, discussed below.

To bring up the standard OS page setup dialog, use
the answer page setupcommand.

answer page setup

8.5.4 Saving Printer Settings
To save or set a complete set of options relating to
the current printer which includesevery setting in the OS Page Setup and Print dialogs, use the printerSettingsglobal property.

The printerSettings property is a binary string that completely describes thecurrent settings. The property contains the name of the printer and
the settings currently
in use.

Caution: You should not attempt to modify the printerSettings but rather get and set itin its entirety. To access individual printer properties, use the global printing properties
described below.
When you set the printerSettings property to a saved value, LiveCode will choosethe printer named in the property and set all of its settings to those contained within theproperty. If the printer cannot be found LiveCode will return the error "unknown printer"
in the result. If the printer is found but the settings are not valid then LiveCode willchoose the printer and reset it to default values.

Note: You must save a separate copy of the printerSettings property for each printer orOS you intend to use. The printerSettings property cannot be transferred between
platforms. For example, a printerSettings property generated on a Windows computer
cannot be used on Mac OS X – even for the same printer. If you want to alter settings
across different platforms and printer types use the global printing properties described
below. Use the printerSettings for convenience when you know you will be using the
to:
Figure 69 – Example geometry properties for print layout stack

To make the printing template stack take on
the size of the paper, we can add thefollowing handler to the stack script:

on preOpenStack

 set
the width of this stack to (item 3 of the \

 printRectangle - item 1 of
the printRectangle)

set the height of this stack to (item 4 of
the \

 printRectangle - item 2 of
the printRectangle)
end preOpenStack

We now have a working print template stack
. All that remains is to write the script thatprints into the rectangles:

-- prepare to load this stack off screen

hide stack "print layout"

-- this will trigger the stack to resize, which run
the
geometry routines, giving us the correct values for eachrectangle

go stack "print layout"

-- now we store these rectangle coordinates in variables

put the rect of graphic "header" into tHeaderRect
put the rect of graphic "body" into tBodyRect
put
the rect of graphic "footer 1" into tFooter1Rect
put the rect of graphic "footer 2" into tFooter2Rect

Changed lines 4442-4476 from:
same printer and want to save all the settings, or where you are setting esoteric propertiesnot listed in the global printing properties described below.
To save the current printer settings into a custom property stored on the current stack:

set the cSavedPrinterSettings of this stack to \

the printerSettingssave this stack

Then to restore these settings:

set the printerSettings to the cSavedPrinterSettings \
of this stack

8.6 Paper Related Options
This section discusses how you get and set paper related options – the rectangle area ofthe paper, the paper size, the orientation and the scale to use to print onto the paper.
These paper options apply to all types of printing, i.e. card, field and layout printing.

Use the printRectangle to get the printable rectangle area within the paper (returned
in device co-ordinates). This property takes into account any settings applied by the user
in the Page Setup and Printer dialogs including the print orientation (e.g. landscape or
portrait). The rectangle is represented left,top,right,bottom and is always relative to thetop left of the page – thus the top left will always be 0,0. The printRectangle will alwaysbe within the printPaperRectangle– the rectangular area of the sheet of paper.

Note: The printRectangle property is read only and cannot be set directly – to
alter it you must set other options relating to the paper, for example the
printPaperOrientation (discussed below).
Important: Do not confuse the printMarginsand other card layout printingproperties with paper properties such as the printRectangle. The
printMargins only applies to printing cards using LiveCode's automatic cardlayout capabilities (discussed below). Thus the printMargins has no effect on
printRectangle.
Use the printPaperOrientation to get and set the orientation of your print out.
This property may be set to one of the following values:


portrait: rotated 0 degrees.
landscape: rotated 90 degrees clockwise.

to:
-- we can close the layout stack as its no longer needed

close stack "print layout"

-- load the system printer dialog to allow the user to
choose number of copies, etc.

answer printer

-- start the print job

open printing

-- set the stack we are working on to a stack containing
the header
-- you could use any stack or region within a card here

set the defaultStack to stack "header graphics"

-- print from the rectangle of our header group into the
rectangle we stored earlier-- we could use a graphic or any rectangular area instead
of a group

print this card from the topLeft of group "header" to the
bottomRight of group "header" into tHeaderRect
set the defaultStack to "body contents"
print this card from the topLeft of group "body" to the
bottomRight of group "body" into tBodyRect
set the defaultStack to "footer1"
print this card from the topLeft of group "footer1" to the
bottomRight of group "footer1" into tFooter1Rect
set the defaultStack to "footer2"
print this card from the topLeft of group "footer2" to the
bottomRight of group "footer2"

-- send the print job to the printer

close printing

-- check to see if the user cancelled or there was an error

if the result is “cancel” then

-- insert any code you need here to handle cancellation

else if the result is not empty then

-- bring up an error dialog

answer “Printer Error”

else

-- insert any code you need here to handle success

end if

For more information on how to print multiple pages of a complex layout, see the section
on Printing Multiple Pages, below. For information on printing scrolling text fields into
an area within a layout, see the section on Working with Scrolling Fields when Layout
Printing, below.

8.11Printing Multiple Pages

8.11.1 Multiple pages using card printing
To print multiple pages when printing cards, simply specify which cards you want to
print as part of the print command.

Changed lines 4511-4548 from:
reverse portrait: rotated 180 degrees clockwise.
reverse landscape: 270 degrees clockwise.

set the printPaperOrientation to "landscape"

Use the printPaperScale property to apply a scale factor to your print out after allother settings have been taking into account.

Note: The printPaperScale is applied after all other layout and scaling options.
For example, if you have used the layout printing features to print a series of cards at50% scale, then set the printPaperScale
, this factor will be applied to the entire
layout after the card
layout scaling has been calculated.
To print a range between 1 and 100% set the printPaperScale to a number between
0 and 1. To print at 200% set the printPaperScale to 2.

set the printPaperScale
to 0.5 -- 50%

8.7 Job Related Options
This section discusses how to get and set job related options – the number of copies
,
duplex printing, collation, color, title and printable area.

Important: The available job options all depend on what the currently selected printer
supports (
use the printerFeaturesproperty, described above, to retrieve a list offeatures supported by the current printer).
Use the printCopies property to get and set the number of copies to print. TheprintCopies should be set to a value of 1 or more.

set the printCopies
to 5 -- print 5 copies

Use the printDuplex property to tell the printer to print double sided. This property
may be set to any of the following values:


none: no double-sided printing
short edge: double-sided printing with tumble (flip the non
-facing page)
long edge: double-sided printing without tumble.


set
the printDuplex to "short edge"

Use the printCollate property to specify whether to interleave multiple copies of aprint job. If a print job has three pages, P1, P2 and P3, with printCollate set to true

to:
print {range}

Examples:

-- prints the current cardprint this card-- prints all cards in the current stackprint all cards-- prints the next 10 cards, starting with the current cardprint 10 cards-- prints card 3 to 7 of the current stackprint card 3 to 7 print marked cards-- prints all cards where the mark property is trueprint marked cards

8.11.2 Multiple pages when using layout printing
To print multiple pages when printing layouts
, use the open printing command to
open a print job. Then print the
layout for the first page (see above). Then use the printbreak command to insert a page break into the print job. Then lay out the second pageand so on. Finally, use the close printing command to send the print job to the
printer.

8.11.3 Working with Scrolling Fields when Layout Printing
To print a single scrolling text field
, use the revPrintText command (see above for
more information). If you want to incorporate the contents of a scrolling field within alayout,
use the pageHeights property to scroll the field each time you print a page,
then print break to move to the next page.

The pageHeights returns a list of values
to indicate how far a scrolling field needs to
be scrolled
to avoid clipping a line of text on each page of your print out. (You should
use this feature in conjunction with the formatForPrinting property, above.)

-- store a list of pageHeightsput the pageHeights of field "body text" into tHeightsList
-- scroll the field to the start
set
the scroll of field “body text” to 0-- start the print jobopen printingrepeat for each line l in tHeightsList

-- clip the field to the bottom of the last visible line
set the height of field “body text” to l-- print the field rectangle-- you may want to add an output "into" rectangle
print this card from the topLeft of field "body text" \

 to the bottomRight of field "body text"
-- print a new page
print break


Changed lines 4544-4577 from:
and printCopies set to 2 the output order will be P1, P2, P3, P1, P2, P3. With
printCollate set
to false the output will be P1, P1, P2, P2, P3, P3.

set
the printCollate to true

Use the printColors property to specify whether to print in color or not. If "color" isnot among the lines of
the printerFeatures then this property will have no effectand all print jobs will be printed in monochrome. This property may be set to either true
or false.

For example, to check if color printing is supported on the current printer and use it if itis:

if "color" is among the lines of the printerFeatures thenset the printColors to true

Use the printTitle property to specify the name of
the next print job in the systemprinter queue. Setting this property to match the name of the user's document will ensurethat the user is able to recognize it in the system printer queue utility. If theprintTitle is empty at the start of a printing loop, the title of the defaultStack
will be used. 

set the printTitle to "My Report 1"

Use the printRectangle property to determine
the printable region of the physicalpage as returned by the printer. This rectangle will always be contained within theprintPaperRectangle. Thus you should use the printRectangle and not the
printPaperRectangle when calculating a print layout. The
printPaperRectangle is useful if you are generating a print preview and want to
show the entire area of
the paper including any margin areas that cannot be printed on.
This property is read only and cannot be set directly.

8.7.1 Printer Font Metrics (Windows)
Windows systems sometimes use different versions of the same font for displaying texton screen and printing. This can result in layouts and line breaks differing between thescreen display and the printed output. To prevent this from happening, you can tellLiveCode
to use the printer fonts for display on screen. To do this, set a stacksformatForPrinting property to true.

Do:

Don't:

Set the formatForPrinting stack Allow the user to directly edit text in fields
property to true before loading a stack in whose formatForPrinting is set to
memory. If the stack is already loaded, true. Attempting to do this may causeset this property to true then save and display anomalies. Set this property to falsereload it. (Save then use Close and and reload the stack first
.
to:
end repeat-- send the job to the printerclose printing

Important: Set the Lock Location (lockLoc) property of the field
to true before
setting the height in the loop above to avoid
the field “drifting” each time you alter theheight.
Tip: Turn off the scroll bar properties (hScrollbarand vScrollbar) of the field
before printing and set
the border width to 0 if you want to avoid printing a border or
scroll bar
.
Tip: You can incorporate scrolling fields into a template print layout stack (see thesection Printing a Complex Layout above) to make it easier to manage printing a
complex layout. Create a field in your template print stack instead of a graphic, turn offthe scroll bar, set the border width to 0,
the lock location to true and then the geometryproperties as per the section above. At the start of each print job, copy the text font and
size by using
the textFont and textSize properties, then the contents of the text
field you want to print using
the htmlTextproperty.
8.11.4 Working with Print Ranges
Use the printRanges property to get a list of pages that
the user has selected in theprinter settings dialog. Use this property when printing to avoid printing pages the user
has not selected. To
use this property, open a system printer dialog, then store theprintRanges in a variable. Then set the printRanges to "all", then send only thepages that were selected (stored in the variable) to the printer.

Note: If you ignore the printRangesproperty LiveCode will handle this settingautomatically. Simply send every page to the printer as normal and LiveCode will ignore
the pages the user has not selected in the print dialog. Handle this option manually only ifyou are printing an extremely complex layout and want to save processing time buildingthe layout for every unselected page.
Use the printPageNumber
to get the number of the page currently being printed
during your printing loop.

Changed lines 4565-4608 from:
Remove from Memory in the File menu). in the File menu).

Generally use stacks with
Create a stack off screen (with formatForPrinting set to true for
formatForPrinting set to true) display on screen, as this will show text that
with your print layout template and copy has been optimized for print display (instead
text into it prior to printing. of screen display), which is harder to read

on screen.
Set the formatForPrinting before
doing any print layout related Use this property on other platforms –
calculations on the stack. Windows is the only platform that uses

different fonts on screen vs. in a print out.
Set the formatForPrinting to true
on any print preview stack being Use the windowBoundingRectdisplayed to the user. property to constrain display of a stack

who's formatForPrinting has been set
to true – this property will be ignored when
the stack is opened or maximized.

Figure 59 – Dos and don'ts of printer font metrics on Windows

8.8 Printing a Card
Once you have set your printer, paper and job options (above) you are now ready to useone of the print commands to start printing. At its simplest, the print card command
allows you to print a card. Later we will discuss ways of printing more complex layouts,
fields and text.

print this card -- prints the current cardprint card 12 -- prints card 12

For more details on how to specify which cards to print, see the print command in the
LiveCode Dictionary.

To print a scale between 1 and 100% set the printScale to a number between 0 and 1.
To print at 200% set the printScale to 2.

Important: The printScaleapplies to each card that you print. It is not related tothe printPaperScale which is applied to the entire print job after all other scaling
calculations have been applied. Thus you may set the printPaperScaleto 0.5 to
print at 50%, then print individual cards at different printScale values. With a
printPaperScale of 0.5, a printScale of 2 would result in that card being
printed at 100%.
When printing a card, use the printMargins to specify the margins around the border
of the card on the page.

to:
8.12Printing a Browser Object

To print the contents of a browser object, use the revBrowserPrint command. For
more information, see the revBrowserPrint command in the LiveCode Dictionary.

Changed lines 4571-4603 from:
Note: When calculating placement on the printed page, all calculations assume thatthere are 72 dots per inch – regardless of platform or printer device. LiveCode will
automatically adjust the print out for resolution of the actual device. This makes it simple
to calculate your printed layout.
-- a one-inch margin on each sideset the printMargins is set to 72,72,72,72

Important: printMargins only applies when using print card directly. It does not
have any effect on printing cards into a layout (described below).
The printCardBorders property specifies whether or not the bevel border around
the edge of a card should appear in the print out.

8.8.1 Card Layout Options
When using the basic print card form of the print command, there are two layout optionsthat allow you to customize the positioning of cards on the printed page. If you requirefurther flexibility, see the section on printing a layout, below.

Use the printRowsFirst property to specify whether cards should be printed acrossand down or down then across.

Consider a simple example of printing multiple cards – this example is useful for printing
labels. In this example we have a stack that contains 8 cards, each one containing amailing label. If you want to try out this example:

*
Create a stack and size it to be small – the size of a mailing label
*
Create a single field, and in the field Inspector turn off the Shared Text property
*
Group the field and in the group property Inspector turn on Behave as
Background
*
Turn on Select Grouped on the Toolbar and select the field
*
Place the contents of the first mailing label into the Contents tab of the Inspector
*
Create 8 more cards, and in each select the field and place the contents of adifferent label
Thus we have a stack that looks like the figure below.

to:
Chapter 9 Deploying Your Application

With LiveCode, it is easy to deploy your application to anyone. With the revWeb plugin
technology you can deploy to modern web browsers on Windows, Mac OS X and Linux.
revWeb is quick, easy and free for users to install. Simply save your stack as a revlet to
run in a browser. You can also deploy desktop revlets that run using the revWeb runtime.

With the standalone building capability in LiveCode you can create a native desktop
application for each operating system you want to support. Users who do not haveLiveCode can run these applications like any other application they download and install.
Standalone applications can have their own identity as true applications, include adesktop icon, document associations and more.

Changed lines 4583-4597 from:
Figure 60 – Print label stack example

Now we will implement the printing commands. If this was a real application you would
probably want to put these in a Print command in the File menu. In this instance you may
execute the following in the multi-line message box (open the Message Box then pressthe second icon to get the multi-line pane).

-- allow the user to choose printer output optionsanswer printerprint 9 cards

Press enter to execute the commands.

The resulting print out will look like the figure below.


Figure 61 – Printing 9 label-sized cards with default settings

to:
9.1 Building a Standalone Application
When you have finished your LiveCode application and what to distribute it you can
build it into a standalone application. These applications do not require users to haveLiveCode. All of LiveCode's feature set is available for use in a standalone application,
with the exception that you cannot set scripts on objects.

The builder itself will let you build standalone applications for any platform it supports,
from any platform it supports (for example you can build a Windows standalone on aMac OS X machine). However, you may wish to check that your application looks and
behaves correctly on each platform you intend to support. Please note it is inherently
harder to debug an application that has been built as a standalone, so you should test your
application as thoroughly as possible before building it.

9.1.1 Standalone Applications Settings
The Standalone Applications Setting dialog allows you to create settings for your
standalone application. This dialog can be found in the File menu. The settings you enter
are applied to the current front most editable stack and are saved with the stack. Thismeans you only need to enter the settings once for each application you create. The samesettings will apply if you do another build in the future.


Changed lines 4601-4617 from:
If we modify the print commands to include an additional line to turn off theprintRowsFirst:

answer printerset the printRowsFirst to falseprint 9 cards

The resulting print out will look like the figure below.


Figure 62 – Printing 9 label-sized cards with printRowsFirst set to false

Use the printGutters property to specify the margin between each card. By defaultthe printGutters are set to 36,36 or one half inch horizontally and vertically.

In the following example, we print the same label stack but reduce the space between
each label to 1/10th of an inch. To make it easy to see the differente we also turn on
printing of card borders using the printCardBorders property.

answer printerset the printGutters to 7,7set the printCardBorders to true

to:
Figure 70 – Standalone Settings – General Tab

Mode Selector
Choose between the different standalone application settings
screens.

Standalone Name
Set the name of your standalone application. This should be the
name you want your finished application to have. Don’t include afile extension (.exe on Windows or .app on Mac OS X) as thestandalone builder can create standalones for multiple platformsand will add the appropriate extension automatically.

Inclusions Choose the components you want to include in a standalone. You
Selector may either choose to search for required inclusions automatically,
or manually select the components you want to include.

Search for Inclusions

This is the default option. When selected, LiveCode will search your application stack
file (main stack and sub stacks) to attempt to determine what components your
application uses. It will then include those items.

Select Inclusions for the Standalone Applications

Select this option if you want to specify the components to include manually. You may
wish to use this option if your application dynamically loads components that cannot besearched at this point automatically, or if you know exactly what components your
application uses and wish to speed up the standalone building process by skipping theautomatic search step.
It is important that you choose to include all the components that your application uses or
it may fail. If you do not include your own custom error reporting or LiveCode’sstandalone error reporting dialog (discussed below) such failure may be silent – i.e. an
operation in your standalone will simply cease working without displaying anything to
the user.

Ask Dialog
This option is required if any of your scripts use the "ask" or "ask
password" commands. The standalone builder will copy the stack
"ask dialog" from the IDE into your standalone as a sub stack. Thestandalone builder makes a copy of your stack before adding
resources to it as part of the build process, so your original stack is
unaltered.

Answer Dialog
This option is required if any of your scripts use the "answer"
command. Note that this only applies to the dialog form of thecommand. The answer file / printer / color / effect / folder / pagesetup / printer and record forms of the command do not requirethis option. The standalone builder will copy the stack "answer
dialog" into your standalone.

Cursors
This option is required if your application uses any of LiveCode's
cursors. It is not required if your application only uses OS cursors.
It copies the stack "cursors" into your standalone.

Print Dialog
This option is required if your application uses LiveCode's built-in

Changed lines 4652-4666 from:
print 9 cards

The resulting print out will look like the figure below.
Figure 63 – Printing 9 label-sized cards with borders and a narrow gutter betweeneach
8.9 Printing Fields & Text
To print a field, use the revPrintField command. This command takes a singleparameter, a reference to a field. This command only allows printing a single field. If you
need to include a header and footer or text you have constructed programmatically, seethe revPrintText command below.

revPrintField the long id of field "text document"

Tip: revPrintFieldis implemented as a script library located in the LiveCodeIDE. The script library creates an invisible stack, sets the rectangle of that stack to the
current paper size, sets the formatForPrinting to true, creates a field, then copies
the contents of the field you specify into this invisible stack. It then prints the field one
page at a time, scrolling the text after each page. Advanced users can locate this library
script by going to the Back Scripts tab in the Message Box, turning on the checkbox for
to:
Brushes

Script Libraries

Animation
Browser
Database
Font SupportGeometryInternet
Printing

LiveCode Zip

SpeechSSL & EncryptionTable
Video Grabber
XML
XMLRPC

Database Support

Profiles Settings

print or page setup dialogs (e.g. for use on Linux without GTKinstalled). It is not required if you only display the system printer
and page setup dialogs. It copies the stack "print dialog" and
"page setup" into your standalone.
This option is required if your application uses any of LiveCode's
brush cursors. It is not required if your application does not makeuse of the painting commands. It copies the stack "brushes" into
your standalone.
This option allows you to copy script libraries into your
standalone.
The list of available libraries is automatically updated to include
any plug-in libraries or externals you may have installed into theLiveCode distribution. Thus the list you have may differ fromwhat is documented here.

When included in a standalone application, each script library is
implemented as a hidden group and made available when the
group receives its first openBackground message. During the
first part of the application startup process before this message is
sent, any commands that use a given library will not be available.
This may affect attempts to use this a script library in startup,
preOpenStack, openStack, or preOpenCard handers in
the main stack. Once the application has finished starting up, thelibrary is available and the script library can be used in any
handler.
This library is unsupported.
Embedded browser and any revBrowser command.
Database access and any revDatabase command.
revFontLoad and revFontUnload.
Geometry properties or commands.
Internet access, including URL, ftp & POSTrevPrintField, revShowPrintDialog and
revPrintText
All revZip commands (but not required for
compress/decompress)
revSpeak and revSpeechVoicesAny SSL or encryption related commands
Use of the table objectAny video capture commandsAny revXML commands
Any revXMLRPC commands

This option is required if you use SQL databases. Ensure you
choose to include drivers for any database you need to access.


Choose between the Property Profile settings options. You only

Changed lines 4713-4747 from:
Show LiveCode UI Back Scripts, then editing the script of button "revPrintBack". The
revPrintField handler is near the top of the script.
Use the revShowPrintDialog command to control whether the system printer and
page setups dialogs should be shown by revPrintFieldor revPrintText.


-- show the system printer dialog, but not page setuprevShowPrintDialog true, falserevPrintField the long id of field "text document"

Use the revPrintText command
to print plain or styled text together with an optional
header and footer.


revPrintText textToPrint [,headerText [,footerText[,fieldTemplate]]]


The textToPrint is anything which evaluates to a string. If you want to printed styled text,
pass HTML instead of plain text. (To convert a field containing styled text to a HTMLuse
the htmlText property.)

The headerText and footerText contains the text to use as a header and footer. You may
include an expression that is computed for each page. For more details on using
expressions, see the LiveCode Dictionary entry for revPrintText.

The fieldTemplate parameter allows you
to specify a field reference to use. Fonts in theprint out will be inherited from this field.

8.10Printing a Layout

If you need to print a more complex layout than allowed with the basic print card
command or text printing commands (described above), you can use the print cardinto rect syntax to create any sort
of layout you choose.

print card from topLeft to rightBottom into pageRect

The topLeft is the top left coordinate of the current card to start printing at.

The rightBottom is the bottom right coordinate of the current card to stop printing at.

The pageRect is the rectangular area on the paper to print into.

Important: printMarginsonly applies when using print card directly. It does nothave any effect on printing cards into a layout. Use the printRectangleto get theprintable area when working with layout printing.
to:
need to alter settings in this area if you have used Property Profiles(see the section on Property Profiles in Chapter 4, Builder a User
Interface above)
(see the section on Property Profiles in Chapter 4, Builder a User
Interface above)

Remove all

Removes all profiles and builds the standalone using the currently

profiles
active profile on each object. Select this option if you don't need
to
change profile in the standalone and want to save disk space by

removing extraneous profile information.

Set all objects to
Set all objects
to a specific profile then remove the profile data

profile
from objects.

Include profiles
Include the profile library and allow switching between profiles in

and the profile

the standalone application. You can choose whether to include

library
specific profiles or all profiles.


Figure 71 – Standalone Settings – Stacks Tab

Stack Files
Use this section to add additional stack files to your application.
Any stacks you add to this section will be added
to thestackFiles property of the main stack of your standalone. Thismeans that any scripts within your standalone application will beable to locate and reference these stacks by name.

Advanced
Use this section to control exactly how multiple stack files are


Options
managed in your standalone.

Move substacks
If you select this option, each
of the sub stacks in the stack files you

into individual
select will be moved into their own individual file, located in the

Changed lines 4761-4773 from:
For example, lets say that we want to print the text field from the middle of the stack in
figure 73 below. (You can load the stack shown in the picture by going to your LiveCodeinstallation folder then opening Resources-> Examples-> SQLite Sampler.rev.) We wantthe output to scale to take up the entire width of the paper and half the height.


Figure 64 – Stack with text field to print into a layout

print this card from the topleft of field "theText" \
to the bottomRight of field "theText" into \
0,0,item 3 of the printRectangle, \
round(item 4 of the printRectangle / 2)

This results in the print out shown in figure 74 below.

to:
files
Rename stackfiles
generically
Rename stackfiles
generically

Create folder for
stackfiles

Individual stack
options
Set destroyStackto true

Encrypt withpassword

data folder or within the application bundle of your standalone.
Renames each sub stack file using a number on disk (instead ofusing the name of the sub stack). Select this option if you do notwant the names you have selected for stacks to be visible to the end
user in the filing system.
Creates a folder and places the stack files into that folder, instead ofstoring them at the same level as the standalone executable. Allreferences in the stackFiles property will refer to this folder
using a relative path so the stacks can still be located by thestandalone application.
Select a stack file on the left then an individual stack from within
the file to set options on that stack.
Set this option if you want the selected stack file to be removed
from memory when it is closed. This option is useful if you areloading large stacks into memory and want them to be removed
when they are closed.
Secures the scripts within the selected stack file with a password.
This provides a basic level of encryption that prevents someonefrom casually reading the scripts in the stack by opening the file in
a binary file viewer.

Note: A stack file directly attached to a standalone application cannot have changes
saved to it. This stack is bound directly to the executable file that runs. The OS locks anexecutable file while it is running. If you want to save changes in your standalone
application, split your stack up until multiple files. A common technique is to create a
"splash screen" stack that contains a welcome screen and then loads the stacks that makeup the rest of your application. These stacks are referenced as stackFileson this
pane in the standalone settings screen. It is thus possible to automatically update these
component stacks, or to save changes to them. You may also want to consider creating
preference files in the appropriate location on your end user's system (see the
specialFolderPath function and query/setRegistry functions for more
information).
Changed lines 4800-4807 from:
Figure 65Result of layout printing command

You can construct a complex layout taking components from multiple stacks by printing
a sequence of rectangles onto the same page. For example, you may have a stack thatcontains a standard header and footer, another that contains a logo, and a layout thatcontains text. Use the open printing command to start a print job, then print each
element into the appropriate rectangle on
the paper. The use then close printingcommand to send the print job to the printer. The example in figure 75 below shows two
stacks with printable regions that we want to combine onto a single sheet of paper.


to:
Figure 72Standalone Settings – Copy Files

Non-stack files in List other files to be included in the standalone. Use this feature to
the application include help documents, read me files and other resources that you

want to include with your standalone each time you build.
Copy ReferencedLoops over all image and player objects in stacks and copies any
Files files referenced in the fileName property of these objects into
the

standalone. Then automatically sets the fileName property
to
reference these files in
the standalone using referenced file paths.
Destination folder Create a subfolder within your standalone to copy the image and
movie files to.

Figure 73 – Standalone Settings – Mac OS Classic

Changed lines 4817-4853 from:
Figure 66 – Separate header and body stacks to print into a layout

To print these onto a single sheet:

answer printer -- show the system print settings dialog
open printing -- start a print job-- work with the header stack

set the defaultStack to "header"

-- print the header field onto the top left of the paper

print this card from the topLeft of field "header" \

to the bottomRight of field "header" into \
the rect of field "header"

-- save the bottom of the header

put
the bottom of field "header" into tHeaderBottom
set
the defaultStack to "report editor"

-- print the table field below
the header

print this card from the topleft of field "report table" \

to the bottomRight of field "report table" into \
0,tHeaderBottom,the right of field "report table", \
the bottom of field "report table" + tHeaderBottom

-- send
the job to the printer

close printing


Figure 67 – Result of layout printing command with multiple stacks

8.10.1 Printing a complex layout
To print a more complicated layout, create a stack and set its rectangle to the currentprintRectangle. Add rectangular areas for each component you will be printing.

to:
Build for Mac OS

Creator signature
Document type
Include resources
from file
Use dynamic
memory
allocation
Minimum /
preferred size

Version number
Long versionstring
Release
Region
Non-release

Builds a standalone for the Mac OS Classic platform. Note that thisbuild option uses the LiveCode 2.6.1 Classic engine. All of thesettings on this pane relate only to the standalone built for Mac OSClassic. They do not affect the other platforms.

Set the creator type for your application
Set the document type for your application
Copy resources from a specified resource file into
the resource fork
of your standalone
Use
the dynamic memory allocator on Mac OS Classic

Set
the minimum and preferred size for your application. Ensurethis is enough to load your application. If you have turned offdynamic memory allocated, ensure this is enough to load all theresources in your application and use the entire feature set
Set the version number, displayed in the Get Info window
Set the version information string, displayed in the Get Info
window
Specify the release type
Specify the region
Specify the non-release version number

Changed lines 4851-4864 from:
Then set Geometry properties (see the section on the Geometry Manager, above for moreinformation) on each of these rectangles so they resize correctly when the stack is scaled.
Set up your print routine so that you open this stack invisibly then resize it to theprintRectangle
. This will trigger the geometry routines and scale the rectangular
areas correctly. Then run your sequence
of print commands to print into each rectangle.

In figure 77 below, we have set the size of the stack to the printRectangle then
added 4 rectangle graphics. We have named each graphic and turned on the Show Name
property for each so you can see the name.


Figure 68 – Stack template for printing a layout

Next, we set Geometry properties for each of the rectangle graphics. The header graphicis set to scale relative to the right and bottom, with a minimum size limit of 100 pixels(see figure 75 below). The body graphic is set to link the top edge to the header graphic,
the right and bottom to the stack (see figure x below). The footer 1 graphic is set to scalethe right edge and position the bottom edge. And footer 2 is set to position both the rightand bottom.

to:
Important: Because the build for Mac OS Classic option builds using the LiveCode
2.6.1 engine, you must make sure that your stack does not use any newer features that
would cause the scripts not to compile. The standalone builder automatically saves thestack in legacy 2
.6.1 format but does not check your scripts. You should check your
stack with a version
of the 2.6.1 IDE and use this facility to build for Classic on stacks
that you know are compatible.
Figure 74 – Standalone Settings – Mac OS X Figure 74 – Standalone Settings – Mac OS X
Mac OS X Build a standalone for Mac OS X in universal binary format. This(Universal) standalone will run natively on both Intel and PowerPC machines.
Mac OS X Build a standalone that will run natively on Mac OS X PowerPC

Changed lines 4861-4893 from:
Figure 69 – Example geometry properties for print layout stack

To make the printing template stack take on the size of the paper, we can add thefollowing handler to the stack script:

on preOpenStack

 set the width of this stack to (item 3 of the \

 printRectangle - item 1 of the printRectangle)

set the height of this stack to (item 4 of the \

 printRectangle - item 2 of the printRectangle)
end preOpenStack

We now have a working print template stack. All that remains is to write the script thatprints into the rectangles:

-- prepare to load this stack off screen

hide stack "print layout"

-- this will trigger the stack to resize, which run the
geometry routines, giving us the correct values for eachrectangle

go stack "print layout"

-- now we store these rectangle coordinates in variables

put the rect of graphic "header" into tHeaderRect
put the rect of graphic "body" into tBodyRect
put the rect of graphic "footer 1" into tFooter1Rect
put the rect of graphic "footer 2" into tFooter2Rect

to:
(PowerPC Only)

Mac OS X (IntelOnly)
Application Icon

Document Icon

Icons for ask /
answer dialogs

PLIST – enter
information and
have LiveCode
write the PLIST

Choose a file to
import into theapplicationbundle
Short version /
long version
Get info string

Copyright notice
Bundle identifier

machines. This standalone will still run on Intel machines, but willload under Rosetta (emulation) so will run much slower. Choose
this option if you want to keep the file size of your standalone down

(e.g. to upload smaller PowerPC and Intel distributions for your
users to choose from and download).
Build a standalone that will run natively on Mac OS X Intelmachines. This standalone will not run at all under PowerPC.
Choose an application icon to represent the application in theFinder. The icon should be in icns format.
Choose a document icon to represent your application's documents
in the Finder. The icon should be in icns format.
Choose an icon to display whenever you use the ask or answer
commands to display a dialog. On Mac OS X, the convention is thatthese dialogs should display your application icon. The icon should
be stored in your stack as an image, or selected from LiveCode's
built-in icons. If you have used a built-in icon, be sure to select therelevant inclusion on the General tab (if you are selecting inclusionsmanually).
Have LiveCode fill out the PLIST for your application
automatically. The PLIST is a settings file stored in XML formatstored as part of every Mac OS X application. It containsinformation about the application, including its name, version
number, copyright notice and document associations. Having
LiveCode create this file for you is the recommended option. For
more information about PLISTs see
http://developer.apple.com/documentation/
Darwin/Reference/ManPages/man5/plist.5.html

Choose to import a PLIST file instead of having LiveCode create
one. Select this option if you have created your own highly
customized PLIST that you want to use for your application in each
build you create.
The version information to be included with your standalone.


The visible text displayed in your application's Get Info window by
the Finder.
The copyright notice for your application.
A unique identifier for your application used by Mac OS X to
identify your application.

Changed lines 4921-4988 from:
-- we can close the layout stack as its no longer needed

close stack "print layout"

-- load the system printer dialog to allow the user to
choose number of copies, etc.

answer printer

-- start the print job

open printing

-- set the stack we are working on to a stack containing
the header
-- you could use any stack or region within a card here

set the defaultStack to stack "header graphics"

-- print from the rectangle of our header group into the
rectangle we stored earlier-- we could use a graphic or any rectangular area instead
of a group

print this card from the topLeft of group "header" to the
bottomRight of group "header" into tHeaderRect
set the defaultStack to "body contents"
print this card from the topLeft of group "body" to the
bottomRight of group "body" into tBodyRect
set the defaultStack to "footer1"
print this card from the topLeft of group "footer1" to the
bottomRight of group "footer1" into tFooter1Rect
set the defaultStack to "footer2"
print this card from the topLeft of group "footer2" to the
bottomRight of group "footer2"

-- send the print job to the printer

close printing

-- check to see if the user cancelled or there was an error

if the result is “cancel” then

-- insert any code you need here to handle cancellation

else if the result is not empty then

-- bring up an error dialog

answer “Printer Error”

else

-- insert any code you need here to handle success

end if

For more information on how to print multiple pages of a complex layout, see the section
on Printing Multiple Pages, below. For information on printing scrolling text fields into
an area within a layout, see the section on Working with Scrolling Fields when Layout
Printing, below.

8.11Printing Multiple Pages

8.11.1 Multiple pages using card printing
To print multiple pages when printing cards, simply specify which cards you want to
print as part of the print command.

to:
Figure 75 – Standalone Settings – Windows

Build for Build a standalone for the Microsoft Windows OS.
Windows
Application icon Choose an application icon to represent the application in

Windows. The icon should be in .ico format.
Document icon Choose a document icon to represent your application's documents

in Windows. The icon should be in .ico format.
Version The version information to be stored as part of your application and
information displayed in the Windows property inspector and dialogs.
Make U3 Build your application for the U3 smart platform. For more
Compatible information on U3 see http://www.u3.com. For more

documentation on building U3 applications using LiveCode, see theResources/Examples/U3 Documentation.pdf file included within
your LiveCode distribution folder.

Changed lines 4940-4971 from:
print {range}

Examples:

-- prints the current cardprint this card-- prints all cards in the current stackprint all cards-- prints the next 10 cards, starting with the current cardprint 10 cards-- prints card 3 to 7 of the current stackprint card 3 to 7 print marked cards-- prints all cards where
the mark property is trueprint marked cards

8.11.2 Multiple pages when using layout printing
To print multiple pages when printing layouts, use the open printing command to
open a print job. Then print the layout for the first page (see above). Then use the printbreak command to insert a page break into the print job. Then lay out the second pageand so on. Finally, use the close printing command to send the print job to the
printer.

8.11.3 Working with Scrolling Fields when Layout Printing
To print a single scrolling text field, use the revPrintText command (see above for
more information). If you want to incorporate the contents of a scrolling field within alayout, use the pageHeights property to scroll the field each time you print a page,
then print break to move to the next page.

The pageHeights returns a list of values to indicate how far a scrolling field needs to
be scrolled to avoid clipping a line of text on each page of your print out. (You should
use this feature in conjunction with the formatForPrinting property, above.)

-- store a list of pageHeightsput the pageHeights of field "body text" into tHeightsList-- scroll the field to the start
set the scroll of field “body text” to 0-- start the print jobopen printingrepeat for each line l in tHeightsList

-- clip the field to the bottom of the last visible line
set the height of field “body text” to l-- print the field rectangle-- you may want to add an output "into" rectangle
print this card from the topLeft of field "body text" \

 to the bottomRight of field "body text"
-- print a new page
print break


to:
Figure 76 – Standalone Settings – Unix

Build for Linux
Build a standalone for Linux

Build for Solaris
Build a standalone for Solaris

Include
Select built-in LiveCode dialogs to include. These dialogs are
useful if your application may be run on a system that does notinclude these dialogs as part of
the OS. You do not need to includethese dialogs if you are running a recent version of GTK.
Changed lines 4953-4972 from:
end repeat-- send the job to the printerclose printing

Important: Set the Lock Location (lockLoc) property of the field to true before
setting the height in the loop above to avoid the field “drifting” each time you alter theheight.
Tip: Turn off the scroll bar properties (hScrollbarand vScrollbar) of the field
before printing
and set the border width to 0 if you want to avoid printing a border or
scroll bar.
Tip: You can incorporate scrolling fields into a template print layout stack (see thesection Printing a Complex Layout above) to make it easier to manage printing a
complex layout
. Create a field in your template print stack instead of a graphic, turn offthe scroll bar, set the border width to 0, the lock location to true and then the geometryproperties as per the section above. At the start of each print job, copy the text font and
size by using
the textFont and textSize properties, then the contents of the text
field
you want to print using the htmlTextproperty.
8.11.4 Working with Print Ranges
Use
the printRanges property to get a list of pages that the user has selected in theprinter settings dialog. Use this property when printing to avoid printing pages the user
has not selected. To use this property, open a system printer dialog, then store theprintRanges in a variable. Then set
the printRanges to "all", then send only thepages that were selected (stored in the variable) to the printer.

Note: If you ignore the printRangesproperty LiveCode will handle this settingautomatically. Simply send every page to the printer as normal and LiveCode will ignore
the pages the user has not selected in the print dialog. Handle this option manually only ifyou are printing an extremely complex layout and want to save processing time buildingthe layout for every unselected page.
Use the printPageNumber to get the number of the page currently being printed
during your printing loop
.
to:
Include Error
Reporting Dialog

htmlText for
dialog

Dialog icon


Allow user to
enter comments

Allow user to save
report
to file
Allow user to
email report

Figure 77 – Standalone Settings – Bug Reports

Include an error reporting stack in your standalone. You should
select this option if you are testing your application
and wantdetails of any errors in your standalone, or if you have not included
your own error reporting routines in your stacks.
The text to display to the user in the dialog that comes up when an
error is encountered. This text should be in LiveCode-compatibleHTML format
. Create and format the text in a LiveCode field then
copy the field's HTMLText property.
The icon to display in the error dialog. This should be stored as an
image in your stack.
Display a box for
the user to give you more information. Thisinformation will be included in the report.
Allow
the user to save the report to a file. Select this option if you
want users to save an error report and send it to you.
Allow
the user to email the report. Select this option if you want theuser to be able to send you or your technical support departmentdetails of the error. This option loads up the system default emailclient and populates the email with the contents of the error reportand the user's comments. The To: field is sent to the email address
specified
in the email address field.
Changed lines 4985-4989 from:
8.12Printing a Browser Object

To print the contents of a browser object, use the revBrowserPrint command. For
more information, see the revBrowserPrint command in the LiveCode Dictionary.

to:
9.2 Distributing On the Web
To distribute for the web, check the Web option in the Standalone Settings dialog. Thiswill allow you to create a revlet, which can be viewed in in popular browsers using thefree, lightweight revWeb plugin. The latest version of the plugin will always be availableat http://revweb.runrev.com/ and you can direct users there to download it. Note thatbuilding for the web is the only option in revMedia.


Figure 78 – Standalone Settings – Web

UUID
A unique ID for your revlet. This is generated automatically and
shouldn’t be changed.

Security
Allows you to specify the security permissions that your revlet
requires. The revWeb Plug-in will request these permissions fromthe user before your revlet is loaded onto the page. Note that if your
stack requires permissions that have not been granted, thosefeatures will not work. Auto-detect attempts to detect the required
settings from the scripts you use.
Network: Allows access to sockets and URLs outside the domain
the revlet resides on.
Disk: Allows access to the user’s local disk. All file access

Changed lines 5005-5015 from:
Chapter 9 Deploying Your Application

With LiveCode, it is easy to deploy your application to anyone. With
the revWeb plugin
technology you can deploy
to modern web browsers on Windows, Mac OS X and Linux.
revWeb is quick, easy
and free for users to install. Simply save your stack as a revlet to
run in a browser. You can also deploy desktop revlets that run using the revWeb runtime.

With the standalone building capability in LiveCode you can create a native desktop

application for each operating system you want to support. Users who do not haveLiveCode can run these applications like any other application they download and install. 
Standalone applications can have their own identity as true applications, include adesktop icon, document associations and more.

to:
commands require this permission.
Registry (Read): Allows reading the registry on Windows using
queryRegistry.
Registry (Write): Allows writing to
the registry on Windows using
setRegistry.
Privacy: Allows access
to the video camera, microphone and screen
capture.
Process / Shell: Allows access to the command line
and the ability
to launch and communicate with other processes.


 Printing: Allows access
to the printer and printer settings.
Platforms The platforms the revlet supports.
supported
Custom load icon Allows you to specify your own custom logo for use on the loading

screen.


Background
Sets the top and bottom colors
to create a gradient color for theloading screen. (Use the same colors for both to create a solid
color
.)
Changed lines 5028-5044 from:
9.1 Building a Standalone Application
When you have finished your LiveCode application and what to distribute it you can
build it into a standalone application
. These applications do not require users to haveLiveCode. All of LiveCode's feature set is available for use in a standalone application,
with the exception that you cannot set scripts on objects.

The builder itself will let you build standalone applications for any platform it supports,
from any platform it supports (for example
you can build a Windows standalone on aMac OS X machine). However, you may wish to check that your application looks and
behaves correctly on each platform you intend to support. Please note it is inherently
harder to debug an
application that has been built as a standalone, so you should test your
application as thoroughly as possible before building it.

9.1.1 Standalone Applications Settings
The Standalone Applications Setting dialog allows you
to create settings for your
standalone
application. This dialog can be found in the File menu. The settings you enter
are applied to the current front most editable stack and are saved with the stack. Thismeans you only need to enter the settings once for each application you create. The samesettings will apply if you do another build in the future.


to:
Chapter 10 Error Handling & Debugging

In an ideal world everyone would write perfect code and there would never be any need
to debug
. However in reality, virtually every project is going to require some degree ofdebugging. The more complex the project the more like this is to be true. Fortunately
LiveCode includes a full plethora of debugging tools and techniques that make it quick
and easy to track down errors. The live run-edit cycle allows
you to see the effect ofcorrections as soon as you make them. And, unlike working in a lower-level language,
when you make a mistake you will receive a human-friendly error message pointing you
to where the error occurred, instead of the
application unexpectedly quitting.

As well
as the set of built-in error reporting and debugging tools, LiveCode also allowsyou complete flexibility over error handling, allowing you to provide a customized
experience
to the end user of your application.
Changed lines 5041-5090 from:
Figure 70 – Standalone Settings – General Tab

Mode Selector
Choose between the different standalone application settings
screens.

Standalone Name
Set the name of your standalone application. This should be the
name you want your finished application to have. Don’t include afile extension (.exe on Windows or .app on Mac OS X) as thestandalone builder can create standalones for multiple platformsand will add the appropriate extension automatically.

Inclusions Choose the components you want to include in a standalone. You
Selector may either choose to search for required inclusions automatically,
or manually select the components you want to include.

Search for Inclusions

This is the default option. When selected, LiveCode will search your application stack
file (main stack and sub stacks) to attempt to determine what components your
application uses. It will then include those items.

Select Inclusions for the Standalone Applications

Select this option if you want to specify the components to include manually. You may
wish to use this option if your application dynamically loads components that cannot besearched at this point automatically, or if you know exactly what components your
application uses and wish to speed up the standalone building process by skipping theautomatic search step.
It is important that you choose to include all the components that your application uses or
it may fail. If you do not include your own custom error reporting or LiveCode’sstandalone error reporting dialog (discussed below) such failure may be silent – i.e. an
operation in your standalone will simply cease working without displaying anything to
the user.

Ask Dialog
This option is required if any of your scripts use the "ask" or "ask
password" commands. The standalone builder will copy the stack
"ask dialog" from the IDE into your standalone as a sub stack. Thestandalone builder makes a copy of your stack before adding
resources to it as part of the build process, so your original stack is
unaltered.

Answer Dialog
This option is required if any of your scripts use the "answer"
command. Note that this only applies to the dialog form of thecommand. The answer file / printer / color / effect / folder / pagesetup / printer and record forms of the command do not requirethis option. The standalone builder will copy the stack "answer
dialog" into your standalone.

Cursors
This option is required if your application uses any of LiveCode's
cursors. It is not required if your application only uses OS cursors.
It copies the stack "cursors" into your standalone.

Print Dialog
This option is required if your application uses LiveCode's built-in

to:
10.1Common Techniques for Solving Problems

If you encounter a problem with your code, there are a number of methods available to
help you track it down. In this section we detail some of the main techniques you may
find useful.

10.1.1 The LiveCode Error Dialog
Often the first thing that will alert you to a problem is an error dialog.


Figure 79 – An Error Dialog

There are two possible types of error dialog. The first is the Execution Error dialog. This
dialog is displayed when your script is running and encounters an error.

In the example above, the script was attempting to access field 100. This field does notexist. When LiveCode encounters a problem like this, execution will halt and the dialog
above will be displayed.

If you know what the error is from looking at it, use the Script button to go directly to thescript and edit it. The line that generated the error will be highlighted in the scriptwindow.

Alternatively, if you need more information the Debug button will load the script in thedebugger at the line the error occurred (see below for more information on using theDebugger). You can then load the Variable Watcher (see below) to see the state of all thevariables at the point where execution was halted.

Changed lines 5064-5123 from:
Brushes

Script Libraries

Animation
Browser
Database
Font SupportGeometryInternet
Printing

LiveCode Zip

SpeechSSL & EncryptionTable
Video Grabber
XML
XMLRPC

Database Support

Profiles Settings

print or page setup dialogs (e.g. for use on Linux without GTKinstalled). It is not required if you only display the system printer
and page setup dialogs. It copies the stack "print dialog" and
"page setup" into your standalone.
This option is required if your application uses any of LiveCode's
brush cursors. It is not required if your application does not makeuse of the painting commands. It copies the stack "brushes" into
your standalone.
This option allows you to copy script libraries into your
standalone.
The list of available libraries is automatically updated to include
any plug-in libraries or externals you may have installed into theLiveCode distribution. Thus the list you have may differ fromwhat is documented here.

When included in a standalone application, each script library is
implemented as a hidden group and made available when the
group receives its first openBackground message. During the
first part of the application startup process before this message is
sent, any commands that use a given library will not be available.
This may affect attempts to use this a script library in startup,
preOpenStack, openStack, or preOpenCard handers in
the main stack. Once the application has finished starting up, thelibrary is available and the script library can be used in any
handler.
This library is unsupported.
Embedded browser and any revBrowser command.
Database access and any revDatabase command.
revFontLoad and revFontUnload.
Geometry properties or commands.
Internet access, including URL, ftp & POSTrevPrintField, revShowPrintDialog and
revPrintText
All revZip commands (but not required for
compress/decompress)
revSpeak and revSpeechVoicesAny SSL or encryption related commands
Use of the table objectAny video capture commandsAny revXML commands
Any revXMLRPC commands

This option is required if you use SQL databases. Ensure you
choose to include drivers for any database you need to access.


Choose between the Property Profile settings options. You only

to:
Note: The Debug button will only appear if Script Debug Mode is checked in theDevelopment menu.
Errors During Compiling

A Script Error dialog is displayed when your script cannot be compiled because of asyntax error. This dialog is typically displayed when you attempt to compile a change to ascript by pressing the Apply button in the Code Editor. Pressing the Script button willselect the line that caused the error. Correct the error then press the Apply button to
compile the script again.

Caution: If a compile error is generated then the entire script to which it applies will not
be compiled, not just the line or handler that contains the error. If other scripts are
attempting to call commands or functions in this script they will not be able to run until
you correct the problem and compile the script again.
Because LiveCode compiles all the scripts within a stack when it loads them, a ScriptError dialog can also be generated when you load a stack from disk for the first time – ifyou saved a stack that contained a script that could not compile.

Important: Do not confuse the Execution Error and Script Error dialogs. The Execution
Error dialog occurs when a script is running and cannot continue due to an error. Theerror dialog will start with the words "executing at [time]". The Script Error dialogappears when you attempt to compile a script that contains a syntax error. The error
dialog will start with the words "compiling at [time]". The Script Error dialog will never
contain a Debug button because the script that generated the error is not running.
Tip: If you turn on the Variable Checking option in the Code Editor, LiveCode will
require that you declare all variables and enclose all literal strings in quotes. It will report
a script compile error if you attempt to use an unquoted literal or do not declare a
variable. This can be useful in catching mistakes before you run a script. Note that if you
turn this option on and attempt to compile an existing script that has not been written in
this way, it will typically generate a large number of errors that need to be corrected
before you can compile it.
10.1.2 Suppressing Errors and Messages
If your stack gets into an unstable state where it is generating a large number of errors,
you may want to temporarily turn off sending messages to the stack or displaying error
messages. This can enable you to edit the stack to make the appropriate changes.

Changed lines 5093-5139 from:
need to alter settings in this area if you have used Property Profiles(see the section on Property Profiles in Chapter 4, Builder a User
Interface above)
(see the section on Property Profiles in Chapter 4, Builder
a User
Interface above)

Remove all
Removes all profiles and builds the standalone using the currently

profiles
active profile on each object. Select this option if you don't need to
change profile in the standalone and want to save disk space by
removing extraneous profile information.

Set all objects to

Set all objects to a specific profile then remove the profile data

profile
from objects.

Include profiles
Include the profile library and allow switching between profiles in

and the profile
the standalone application. You can choose whether to include

library
specific profiles or all profiles.


Figure 71 – Standalone Settings – Stacks Tab

Stack Files
Use this section to add additional stack files to your application.
Any stacks you add
to this section will be added to thestackFiles property of the main stack of your standalone. Thismeans that any scripts within your standalone application will beable to locate and reference these stacks by name.

Advanced
Use this section to control exactly how multiple stack files are

Options
managed in your standalone.

Move substacks
If you select this option, each of the sub stacks in the stack files you

into individual
select will be moved into their own individual file, located in the

to:
To suppress messages, press the Messages button on the toolbar or choose SuppressMessages from the Development menu. Normal system event messages will stop being
sent to the stack (for example clicking a button will no longer trigger
a mouseUp handler,
changing card will no longer trigger an openCard handler). You can still send custommessages directly to objects within the stack.

To suppress errors, press the Errors button on the toolbar or choose Suppress Errors fromthe Development menu. This will prevent any errors from triggering an error display

window.

Caution: Be sure
to turn messages and errors back on when you have finished editing.
Otherwise your stack will not work, or any error that comes up during stack operationwill cause execution to halt but will not display an error message.
Tip: You can execute a single navigation command in the message box with a
similar effect as Suppress Messages by including the statement lock messages;
before it. for example,
to go to the next card lock messages; go nextor to exit
LiveCode (without displaying triggering any close messages or asking to save changes
lock messages; quit
10.1.3 Outputting information as your script executes
If you want to know about the state of a particular variable or condition during execution,
you can use the Variable Watcher, detailed below. However sometimes you may want to
run a script without opening the debugger, outputting information along the way. You
can use the put command to output information to the Message Box, a field or a text
file, the write command to output to the Console, or the answer command to display
a dialog.

Output to the Message Box

The Message Box is a convenient way to output information while a script is running. Itallows you to display the information you want within the IDE without having to create afield or stack to display the information. Using a put command without specifying adestination outputs to the Message Box:

put tVar

In the example above, substitute tVar with the name of the variable in your script that you
want to see the contents of. You can also output information only if a certain condition ismet:

if tVar is true then put tData

Changed lines 5127-5164 from:
files
Rename stackfiles
generically
Rename stackfiles
generically

Create folder for
stackfiles

Individual stack

options
Set destroyStackto true

Encrypt withpassword

data folder or within the application bundle of your standalone.
Renames each sub stack file using a number on disk (instead ofusing the name of the sub stack). Select this option if you do notwant
the names you have selected for stacks to be visible to the end
user in
the filing system.
Creates a folder and places the stack files into that folder, instead ofstoring them at the same level as the standalone executable. Allreferences in the stackFiles property will refer to this folder
using a relative path so the stacks can still be located by thestandalone application.
Select a stack file on the left then an individual stack from within
the file to set options on that stack.
Set this option if you want the selected stack file to be removed
from memory when
it is closed. This option is useful if you areloading large stacks into memory and want them to be removed
when they are closed.
Secures the scripts within the selected stack file with a password.
This provides
a basic level of encryption that prevents someonefrom casually reading the scripts in the stack by opening the file in
a binary file viewer.

Note: A stack file directly attached to a standalone application cannot have changes
saved to it. This stack is bound directly to the executable file that runs
. The OS locks anexecutable file while it is running. If you want to save changes in your standalone
application, split your stack up until multiple files. A common technique is to create a
"splash screen" stack that contains a welcome screen and then loads the stacks that makeup
the rest of your application. These stacks are referenced as stackFileson this
pane in the standalone settings screen. It is thus possible to automatically update these
component stacks, or to save changes to them. You may also want to consider creating

preference files in the appropriate location on your end user's system (see the
specialFolderPath function and query/setRegistry functions for more
information).
to:
Whenever you display something in the message box, a special global variable called
message (often abbreviated to msg) is updated. This allows you to check the contentsof the message box easily, as well as add or append information rather than replacing it.

-- puts tInformation and a return after the data
--already in
the message boxput tInformation & return after msg

For more information, see
the section on the Message Box, above.

Output to Standard Out (stdOut or
the Console on Mac OS X)

The stdOut is a useful place to log messages. Unlike
the Message Box, it is easy to log asequence of events which you can then scroll back to review later on. It also has theadvantage of being external to LiveCode so using it does not interfere with your
application window layering or focus in any way. The stdOut is only available on Linux,
Unix or Mac OS X systems. On Mac OS X,
it can be accessed by opening the Consoleapplication, located in the Utilities folder within Applications.

The syntax
to write something to stdOut or the Console is:

write tMessage & return to stdout

Tip: If you are writing
a lot of data out to the console, it can be useful to append the time
to each one to make it easier to debug. write tMessage && the long time &
return to stdOut. If you need more granualarity than seconds, use the
milliseconds instead of the long time
.
Tip: If you are inserting debugging output statements into your code, consider making
them conditional on a global variable. This allows you to turn on debugging by setting
the variable without making changes to code. Even better it prevents forgotten debugging
code in your application inadvertently filling
the console with messages on an end user's
system.
if gDebugging then write tMessage & return to stdOut
Output to a field

You can create a stack that contains fields used for debugging:

put tVar & return after field "debugging info" of \
stack "my debug stack"

Changed lines 5163-5178 from:
Figure 72 – Standalone Settings – Copy Files

Non-stack files in List other files
to be included in the standalone. Use this feature to
the application include help documents, read me files and other resources that you

want to include with your standalone each time you build.
Copy ReferencedLoops over all image and player objects in stacks and copies any
Files files referenced in the fileName property of these objects into the

standalone. Then automatically sets the fileName property to
reference these files in the standalone using referenced file paths.

Destination folder Create a subfolder within your standalone to copy the image and
movie files
to.

Figure 73 – Standalone Settings – Mac OS Classic

to:
Tip: You may want to create a set of tools that makes it easy to debug a specific
application you are working on. Create this stack then save it into your plug-ins folder so
it is available from the Development menu in the IDE.
Output to a dialog

To display a dialog with the contents of a statement, use the answer command. Thismethod is suitable if you want to output something quickly, but is usually unsuitable for
larger debugging tasks as it pauses execution to display a dialog each time


if tVar is true then answer tVar

Output
to a text file

If you want
to log information more permanently, you can use a text file. You may wantto store the file path in a global variable so you can change it easily. See the section on
using file URLs, below for more information.

put tVar & return after URL "file:debug.txt"

10.1.4 Interrupting Execution
If you need to interrupt a script while it is running, press control-period (or commandperiod
on Mac OS). Note that interrupting a script will only work if the globalallowInterrupts property is set to true.

Tip: On Mac OS X systems, if your application has got into an unstable state and you are
unable to interrupt it with command-period you may be able to interrupt it and regain
control by sending it a signal. Open the Terminal utility and then use top -o cpu or ps axto retrieve the process ID for LiveCode. Then run kill -sighup [processID] where
[processID] is the ID of the LiveCode process.
10.2The Debugger

Typically when you want to track down a problem with your script, you will want to usethe debugger. The debugger provides a simple interface that allows you to step through
your script line by line as it executes. You can see the results of each statement as ithappens. If you load the Variable Watcher from within the debugger, it will show you thecontents of all of the variables used in a particular handler. These values will be updated
as you step through. You can even edit these values while your script is running. This can
be useful if you spot a problem in a given area or want to test a section of code with adifferent set of data as it runs.

To activate the debugger, first ensure that Script Debug Mode is turned on in theDevelopment menu. Then open up the script you want to debug and click in the gray bar
to the left of the line where you want to open the debugger. Alternatively you can write

Changed lines 5199-5231 from:
Build for Mac OS

Creator signature
Document type
Include resources
from file
Use dynamic
memory
allocation
Minimum /
preferred size

Version number
Long versionstring
Release
Region
Non-release

Builds a standalone for the Mac OS Classic platform. Note that thisbuild option uses
the LiveCode 2.6.1 Classic engine. All of thesettings on this pane relate only to the standalone built for Mac OSClassic. They do not affect the other platforms.
Set the creator type for your application
Set
the document type for your application
Copy resources from a specified resource file into the resource fork
of your standalone
Use the dynamic memory allocator on Mac OS Classic

Set the minimum and preferred size for your application. Ensurethis is enough
to load your application. If you have turned offdynamic memory allocated, ensure this is enough to load all theresources in your application and use the entire feature set
Set the version number, displayed
in the Get Info window
Set
the version information string, displayed in the Get Info
window
Specify
the release type
Specify
the region
Specify the non-release version number

to:
the command breakPoint into the script. Using the breakPoint command allows
you to break conditionally – if tVar is true then breakPoint.

Next run your script as normal. When LiveCode reaches a breakpoint it will pauseexecution and load up
the debugger. 

Important: To see the contents of variables while your script is running, wait
for thedebugger to open then choose Variable Watcher from the Debug menu. For more
information on using
the Variable Watcher, see below.
Figure 80 – The Debugger

For a table describing each of the buttons in the debugger together with their keyboard
shortcuts, see the section on The Debug Menu in chapter 3.

Press the Step Into button
to execute the current line and move to the next line. Step Over
performs the same action, except that if the current line calls a function it will run thatentire function without opening it
in the debugger.

Once you have found
the cause of the problem, press the Run button to exit the debugger
and run
the script at full speed. Alternatively press the Abort button to halt execution on
the current line and edit the script.

Changed lines 5219-5227 from:
Important: Because the build for Mac OS Classic option builds using the LiveCode
2.6.1 engine, you must make sure that your stack does not use any newer features that
would cause the scripts not to compile. The standalone builder automatically saves thestack in legacy 2.6.1 format but does not check your scripts. You should check your
stack with a version of the 2.6.1 IDE and use this facility to build for Classic on stacks
that you know are compatible.
Figure 74 – Standalone Settings – Mac OS X Figure 74 – Standalone Settings – Mac OS X
Mac OS X Build a standalone for Mac OS X in universal binary format. This(Universal) standalone will run natively on both Intel and PowerPC machines.
Mac OS X Build a standalone that will run natively on Mac OS X PowerPC

to:
Tip: To improve the performance when debugging a complex script, set a breakpointfurther down in the script during the debugging process and press the Run button instead
of pressing Step Over. The debugger is temporarily deactivated until the new breakpoint
is reached, which means the script runs at full speed. When using Step Over, the
debugger is still active even though it does not display a routine as it runs, which is
slower.
10.3The Variable Watcher


Context menu
Choose the execution context to display. This will show all theavailable contexts that are currently executing. For example, if you
have a button that has called a function and you are currently
paused within that function, the variables displayed will be for thatfunction. But you can go back and look at the variables in thehandler that called the function by choosing it from this menu.

Conditional
Attach a conditional breakpoint to a variable. In the example above,

breakpoints
if you want a breakpoint to be triggered when tVar contains 2, click
on the breakpoint area to the left of tVar and type tVar = 2 into thedialog. Press the Run button in the debugger. Execution will halt iftVar becomes equal to 2.

List of variables
This lists all the variables in the current execution context. The
contents of each variable is listed in the area on the right. If thecontents is truncated, click on a variable to have the full contentsdisplayed in the edit area at the bottom. The display area is updated
each time you step to the next line while debugging.

Edit area
Display and the contents of the currently selected variable. To
change the content, simply enter a new value.

Edit script
Go to the Code Editor or debugger window for the current

Changed lines 5252-5310 from:
(PowerPC Only)

Mac OS X (IntelOnly)
Application Icon

Document Icon

Icons for ask /
answer dialogs

PLIST – enter
information and
have LiveCode
write the PLIST

Choose a file to
import into theapplicationbundle
Short version /
long version
Get info string

Copyright notice
Bundle identifier

machines. This standalone will still run on Intel machines, but willload under Rosetta (emulation) so will run much slower. Choose
this option if you want to keep the file size of your standalone down

(e.g. to upload smaller PowerPC and Intel distributions for your
users to choose from and download).
Build a standalone that will run natively on Mac OS X Intelmachines. This standalone will not run at all under PowerPC.
Choose an application icon to represent the application in theFinder. The icon should be in icns format.
Choose a document icon to represent your application's documents
in the Finder. The icon should be in icns format.
Choose an icon to display whenever you use the ask or answer
commands to display a dialog. On Mac OS X, the convention is thatthese dialogs should display your application icon. The icon should
be stored in your stack as an image, or selected from LiveCode's
built-in icons. If you have used a built-in icon, be sure to select therelevant inclusion on the General tab (if you are selecting inclusionsmanually).
Have LiveCode fill out the PLIST for your application
automatically. The PLIST is a settings file stored in XML formatstored as part of every Mac OS X application. It containsinformation about the application, including its name, version
number, copyright notice and document associations. Having
LiveCode create this file for you is the recommended option. For
more information about PLISTs see
http://developer.apple.com/documentation/
Darwin/Reference/ManPages/man5/plist.5.html

Choose to import a PLIST file instead of having LiveCode create
one. Select this option if you have created your own highly
customized PLIST that you want to use for your application in each
build you create.
The version information to be included with your standalone.


The visible text displayed in your application's Get Info window by
the Finder.
The copyright notice for your application.
A unique identifier for your application used by Mac OS X to
identify your application.

to:
execution context.

10.4Custom Error handling

If you are creating an application that is going to be distributed, you may want to includea method for catching and handling errors. LiveCode provides two such methods. Thefirst is the try/catch control structure. This control structure can be inserted around
any routine that you know may encounter problems when in use. For example, you may
wish to include this around a routine that reads in a file from disk to handle the case
where a corrupted file has been selected. The second method is to write a customerrorDialog routine. Unlike a try/catch control structure, an errorDialoghandler is global to your application (or card or stack within an application) and does notprovide a mechanism to allow a script that encounters an error to continue. Use thismethod to display a custom error dialog when an error occurs that you are unable to
predict and report using try/catch.

Using try/catch

Enclose code that may be error prone within a try control structure. The following
example shows a routine that opens and reads from a file enclosed in a try statement. Ifan execution error occurs in any of the statements after the start of the try controlstructure, the catch clause will be triggered with the details of the error. In the examplebelow we declare a variable someError to contain details of the error.

try

open file tFile

read from file tFile until eof

 close file
catch someError

 answer "An error occurred reading a file" && someErrorend try

Tip: The data returned to the error routine is returned in the internal format that
LiveCode uses to display execution errors. To look up the human friendly string
associated with a particular error, look at the first item returned against the list ofexecution errors stored in the LiveCode IDE.
put line (item 1 of someError) of the cErrorsList of \
card 1 of stack "revErrorDisplay"
This will only work in the IDE.
If you want to include statements that will be run regardless of whether there has been an
error or not, include the statements as part of a finally clause.

Changed lines 5288-5305 from:
Figure 75 – Standalone Settings – Windows

Build for Build a standalone for the Microsoft Windows OS.
Windows
Application icon Choose an application icon
to represent the application in

Windows. The icon should be in .ico format.

Document icon Choose a document icon to represent your application's documents

in Windows. The icon should be in .ico format.
Version The version information to be stored as part
of your application and
information displayed in
the Windows property inspector and dialogs.
Make U3 Build your application for the U3 smart platform. For more
Compatible information on U3 see http://www.u3.com. For more

documentation on building U3 applications using LiveCode, see theResources/Examples/U3 Documentation.pdf file included within
your LiveCode distribution folder
.
to:
To create readable error messages for cases where you anticipate there may be an error,
use the throw keyword. For example, if we want
to display an error message when theresult for opening a file returns something:

open file tFileif the result is not empty then throw the result

In the example above, if the file cannot be opened and the result is set, the value
of theresult will be passed to the catch statement in the someError variable.

Writing a custom errorDialog routine

When an execution error occurs, an errorDialog message is sent. The IDE uses thismessage to display the execution error dialog. However you can write and include your
own custom errorDialog routine
. This is useful if you are planning to distribute your
application. For example, you could create a stack that transmits the error information
directly to your technical support department or displays a custom message on screen. Abasic errorDialog routine is shown below:

on errorDialog pError

answer "There was an error" && pErrorend errorDialog

This routine will also be activated if you use the throw keyword to throw an error
(outside of a try/catch control structure).

10.5The Message Watcher

The Message Watcher lets you see what messages are sent during a particular operation.
it can be useful if you want to create a log of the sequences of messages generated during
a particular operation. It also logs how long each message takes to run. This makes ituseful when you are looking for bottlenecks in your code. The Message Watcher islocated in the Development menu.


Changed lines 5317-5328 from:
Figure 76 – Standalone SettingsUnix

Build for Linux

Build a standalone for Linux

Build for Solaris
Build a standalone for Solaris

Include
Select built-in LiveCode dialogs to include. These dialogs are

useful if your application may be run on a system that does notinclude these dialogs as part of the OS. You do not need to includethese dialogs if you are running a recent version of GTK.
to:
Message list area
Figure 81
The Message Watcher Window
Lists messages as they happen. The format is the name of the
message, the time the message was sent and the number of

milliseconds since the last message. Click to select a message,
double click to open it in the Code Editor
.
Object field
Message type
Active
Clear
Suppress
In the example above we can see that the user was inactive for 4.7
seconds before moving the mouse over an object that triggered a
mouseEnter message. 599 milliseconds later they clicked the mouse
triggering a mouseUp message. The mouseUp handler called
calculateResult 0 milliseconds later, then formatData was called
147 milliseconds later. Because there were no user-generated
messages in the sequence, we know that the calculateResult handler
took 147 milliseconds to run.
Shows the object that the message was sent to. Click on a line in theMessage List to update this field.
Shows the type for the selected message – command, function,
getProp or setProp
Check this box to activate the Message Watcher. Deactivate theMessage Watcher when you have captured information about thesequence of events you are interested in and want to stop the
logging of additional messages.
Clears the message list field.
Allows you to set what messages you want displayed and which
ones you want to suppress. Use this option to narrow down themessages that are logged so you can see information about the
sequence you are interested in. See below for more information.


Figure 82 – Suppress Messages Option Screen

Changed lines 5350-5380 from:
Include Error
Reporting Dialog

htmlText for
dialog

Dialog icon

Allow user
to
enter comments
Allow user to save
report to file
Allow user to
email report

Figure 77 – Standalone Settings – Bug Reports

Include an error reporting stack in your standalone. You should
select this option if you are testing your application and wantdetails of any errors in your standalone, or if you have not included
your own error reporting routines in your stacks.
The text
to display to the user in the dialog that comes up when an
error is encountered. This text should be in LiveCode-compatibleHTML format. Create and format the text in a LiveCode field then
copy the field's HTMLText property.
The icon to display in the error dialog. This should be stored as an
image in your stack.
Display a box for the user to give you more information
. Thisinformation will be included in the report.
Allow the user to save the report to a file. Select this option if you
want users to save an error report and send it to you.
Allow the user to email the report. Select this option if
you want theuser to be able to send you or your technical support departmentdetails of the error. This option loads up the system default emailclient and populates the email with the contents of the error reportand the user's comments. The To: field is sent to the email address
specified in
the email address field.
to:
Action – Handled Don't log any message that causes a handler to run when it is sent.
Action – Not Don't log any message that does not cause a handler to run when itHandled is sent. This is the default option and prevents the log from filling
– Handled Don't log any message that causes a handler to run when it is sent.
Action – Not Don't log any message that does not cause a handler
to run when itHandled is sent. This is the default option and prevents the log from filling

up with messages that do not cause any scripts to run.

IDE Messages
Do not log LiveCode IDE messages. The LiveCode IDE generateslots of messages as it is written in LiveCode. This is the defaultoption but you may wish to display these messages if you arecustomizing the LiveCode IDE
.

Handler Type
Do not log
the selected type of handler. For example, to preventdisplaying all function calls, check the function box.

Message list
A list of messages not to log. By default mouseMove is listed as
otherwise mouseMove messages may flood the display whenever

you move the mouse.

Add Add a message name to prevent it from being logged.
Delete Delete a message name to cause it to be logged in
the future.

10.6Tracking Down Problems in Standalone Applications

We recommend that you debug your application as fully as possible in
the IDE, so thatyou can use the Debugger and other tools. However occasionally you may need to track
down a problem that only occurs in a standalone application. If this happens, use thetechniques described above for writing information out to the stdOut or a text file. You
can also include an error display dialog using the Bug Reports tab within the Standalone
Settings screen. Be sure to check either the Allow user to save report to file or Allow user
to email report buttons so that you can view the error generated. For more information,
see the chapter on Distributing your Application
.