LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.

0 DU 15 AOÛT 2013 PAGE 1

11.! CUSTOM PROPERTIES!

!
! Avertissement 1 : le présent chapitre se base sur la documentation officielle de LiveCode établie par!
! RunRev (révision 19 du 09/11/2010) ainsi que sur le chapitre 21 : Defining and Using Custom!
! Properties partie du volume 2 du livre «Revolution, Software At The Speed Of Thought» de Dan!
! Shafer publié en 2003 par Runtime Revolution Ltd.!
! Le présent chapitre reprend, en les adaptant, de nombreux exemples de ces deux publications.!
!
! Avertissement 2 : le terme anglais «custom property» peut être traduit par «propriété!
! personnalisée», mais, pour la cohérence du propos, étant donné que cette expression fait partie!
! intégrante de l’IDE (integrated development environnement / environnement de développement),!
! il m’a semblé préférable de conserver la forme originale encadrée par des guillemets, ce qui permet!
! de conserver le concept recouvert par l’expression.!
! Le même principe a été retenu pour ce qui concerne le terme «virtual property» qui peut être!
! traduit par «propriété virtuelle».!
! D’autres termes propres aux langages xTalk (HyperTalk, SuperTalk, AppleScript, Transcript, LiveCode,!
! etc.) tels que «stack», «stack file», «backScript», «handler» (cf. chapitre 04), «message path» (cf. chapitre 5),!
! «message box», «container», «chunk expression», «player», «trigger», «popover» (environnement Mac OS!
! X), «scrollBar», «card», «owner» ont gardé leur forme anglaise pour les mêmes raisons.!
!
! 11.01.! Principes de base concernant les «custom properties»!
!
! ! 11.01.01.! Qu’est-ce qu’une «custom property» ?!
!
! ! ! Dans les chapitres précédents et notamment le chapitre 10, nous avons vu que!
! ! ! chaque objet se différenciait des autres objets du même type par des propriétés!
! ! ! propres à ce type dont les valeurs sont propres à cet objet. Certains objets ont un!
! ! ! nombre important de propriétés alors que d’autres en ont moins. Une grande partie!
! ! ! de la programmation LiveCode consiste à déterminer les valeurs de ces différentes!
! ! ! propriétés et à commander une action en rapport avec celles-ci ou bien à changer!
! ! ! ces mêmes valeurs.!
! ! ! Par exemple, pour qu’un bouton devienne inactif vous devez régler sa propriété!
! ! ! enabled sur false ou sa propriété disabled sur true. Vous remarquerez!
! ! ! qu’en changeant son état enabled vous affectez non seulement son apparence!
! ! ! mais également son comportement (lorsqu’il est disabled il ne réagit plus au clic!
! ! ! de la souris).!
!
! ! ! Une «custom property» est une propriété que vous créez pour un objet déterminé et !
! ! ! qui s’ajoute aux propriétés déjà définies par LiveCode pour cet objet.!
! ! ! Vous pouvez créer des «custom properties» pour n’importe quel objet (stack, card,!
! ! ! field, button, etc.) et les utiliser pour stocker n’importe quel type de données.!
!
! ! ! Une «custom property» est identique à une propriété déjà présente dans LiveCode!
! ! ! sauf qu’elle n’a pas de valeur par défaut significative et que sa valeur n’est pas!
! ! ! héritée des objets situés plus haut dans la hiérarchie comme c’est le cas dans la!
! ! ! plupart des propriétés intégrées à LiveCode.!
! ! ! Une «custom property» s’applique uniquement à l’objet auquel il est attaché et non,!
! ! ! comme c’est le cas pour les propriétés intégrées, à tous les objets d’un même type.!
! ! ! Ainsi si vous créez une «custom property» pour un bouton spécifique, celle-ci!
! ! ! n’existera que pour ce bouton et non pour tous les boutons de l’application. Alors!
! ! ! que tous les boutons ont en commun les propriétés intégrées (telles que hauteur!
! ! ! [height], largeur [width], couleur [color], activé [enabled], désactivé [disabled]),!
! ! ! lorsque vous définissez une «custom property» pour un bouton spécifique, ce!
! ! ! bouton seulement reconnaîtra cette propriété et réservera pour vous un espace!
! ! ! pour stocker la valeur de cette propriété.!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 2

! ! ! Il existe une sorte de «custom property» appelée «virtual property» pouvant être!
! ! ! utilisée par des scripts pour obtenir un effet plus global qu’avec une «custom!
! ! ! property» ordinaire. Ce type de «custom property» fait l’objet du § 11.05 plus loin!
! ! ! dans ce chapitre.!
!
! ! 11.01.02.! Quand utiliser une «custom property» ?!
!
! ! ! Pour chaque objet composant votre application vous pouvez créer autant de!
! ! ! «custom properties» que vous souhaitez dans lesquelles vous pouvez stocker toutes!
! ! ! sortes de données, y compris des données au format binaire, des données sous!
! ! ! forme de fichier ou de groupes d’objets et même sous forme de stack complet.!
!
! ! ! Créez une «custom property» lorsque vous voulez, par exemple :!
! ! ! –! associer des données à un objet spécifique (ce qui permet, le cas échéant de!
! ! ! ! copier un objet avec ses données associées),!
! ! ! –! enregistrer des données avec un objet dans un «stack file»,!
! ! ! –! accéder rapidement à certaines données,!
! ! ! –! créer des contrôles complexes (sous forme de «stacks») à la volée.!
!
! ! 11.01.03.! Comment créer une «custom property» ?!
!
! ! ! Il existe 2 manières très différentes de créer une «custom property» :!
!
! ! ! –! la première, à l’aide d’un handler ou de la «message box», à partir d’une ligne de!
! ! ! ! code, en attribuant une valeur à une nouvelle propriété désignée par son nom.!
! ! ! ! Dans l’exemple suivant, une «custom property» nommée cpNuméroSession!
! ! ! ! est créée attachée au bouton btnSession :!
!
! ! ! ! set the cpNuméroSession of btn “btnSession“ to 10!
!
! ! ! –! la seconde, dans le cadre de l’IDE, selon le processus suivant, pour le même!
! ! ! ! exemple :!
! ! ! ! après avoir créé un bouton btnSession, sélectionnez-le :! !

! ! ! ! !
! ! ! ! affichez ses propriétés à l’aide de l’inspector, choisissez «custom properties» dans!
! ! ! ! le pop-up menu (5ème item à partir du haut) :!
!

! ! ! ! !
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 3

! ! ! Cliquez sur le bouton à droite de «Custom properties», un dialogue apparaît :!

!

! ! ! !
! ! ! ! !! !
! ! ! Entrez le nom de la «custom property» nouvellement créée cpNuméroSession et!
! ! ! cliquez sur «OK».!
!
! ! ! Le nom de la «custom property» créée apparaît désormais dans le champ réservé à la !
! ! ! liste des «custom properties» :!
!

! ! ! !
! ! ! Pour affecter une valeur à cette «custom property», sélectionnez!
! ! ! «cpNuméroSession» dans la liste, cliquez dans le deuxième champ en bas de!
! ! ! l’inspecteur nommé «Property Contents» et entrez la valeur 10 :!
!

! ! ! !
! ! ! la «custom property» «cpNuméroSession» est créée et a pour valeur 10.!
!
! ! ! La valeur de cet exemple est très simple. D’autres valeurs peuvent être entrées dans!
! ! ! le champ «Property Contents» tel que des listes ou des tableaux de nombres ou de!
! ! ! mots, par exemple :!
!

! ! ! !
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 4

! ! ! Dans l’exemple ci-dessus, la présentation se fait en tableau en cliquant sur le!

! ! ! bouton .!
!
! ! ! Le nom d’une «custom property» doit être composé d’un seul mot et peut contenir!
! ! ! toute composition de lettres, chiffres ainsi que le caractère «tiret bas» ( _ ).!
! ! ! Le premier caractère peut être soit une lettre soit un «tiret bas».!
!
! ! ! Evitez de donner à une «custom property» le même nom qu’à une variable car dans!
! ! ! ce cas LiveCode utilisera le contenu de la variable à la place du contenu de la!
! ! ! «custom property» provoquant des comportements inattendus...!
! ! ! Pour éviter ce type de problème, il est possible de faire précéder le nom!
! ! ! caractéristique distinguant votre «custom property» des caractères «cp» comme!
! ! ! dans les exemples ci-dessus.!
!
! ! ! Important : les noms de «custom properties» commençant par «rev» sont réservés!
! ! ! aux «custom properties» de LiveCode. Donner à une «custom property» un nom!
! ! ! réservé peut produire des résultats inattendus lorsque vous travaillez dans!
! ! ! l’environnement de développement.!
!
! ! 11.01.04.!Comment supprimer une «custom property» ?!
!
! ! ! LiveCode ne dispose pas de commande permettant la suppression d’une «custom!
! ! ! property». Néanmoins, si vous placez tous les noms des «custom properties» dans!
! ! ! une variable, vous pouvez supprimer le nom de celle dont vous ne voulez plus dans!
! ! ! cette variable ; il vous suffit alors de mettre à jour la liste des noms des «custom!
! ! ! properties» à l’aide de la propriété customKeys attachée aux «custom properties»!
! ! ! de l’objet.!
! ! ! Par exemple, le script qui suit a pour effet de supprimer une «custom property»!
! ! ! nommée propertyToRemove attachée au bouton btnBouton :!
!
! ! get the customKeys of btn “btnBouton“
set the wholeMatches to true
delete line lineOffset(“propertyToRemove“,it) of it
set the customKeys of btn “btnBouton“ to it!
!
! ! ! Vous pouvez également supprimer une «custom property» depuis le panel «Custom!
! ! ! Properties» dans l’inspector de l’objet : sélectionnez la «custom property» à !
! ! ! supprimer :!
!

! ! ! !
! ! ! puis cliquez sur l’icône de suppression .!
!
! ! 11.01.05.! Modifier une partie d’une «custom property»!
!
! ! ! Comme les propriétés intégrées, les «custom properties» ne sont pas des!
! ! ! «containers» de sorte que vous ne pouvez pas utiliser une «chunk expression» pour!
! ! ! modifier une partie de la «custom property». Vous pouvez néanmoins mettre la!
! ! ! valeur de la «custom property» dans une variable et modifier la variable, puis vous!
! ! ! remplacez la valeur de la «custom property» par la nouvelle valeur de la variable, par!
! ! ! exemple :!
!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 5

! ! ! local vlVariable
put the cpLastCall of this card into vlVariable
put “mars“ into word 3 of vlVariable
set the cpLastCall of this card to vlVariable!
!
! ! 11.01.06.!Faire référence à une «custom property»!
!
! ! ! Faire référence à une «custom property» c’est la même chose que de faire référence!
! ! ! à une propriété intégrée : il suffit de faire se suivre le mot the, le nom de la!
! ! ! «custom property», le mot of et la référence à l’objet.!
! ! ! Par exemple, pour utiliser une «custom property» nommée cpDernierAppel
! ! ! attachée à une carte (card), servez vous de la ligne de code suivante :!
!
! ! ! put the cpDernierAppel of this card into fld “date“!
!
! ! ! Comme les propriétés intégrées, les «custom properties» sont une source de valeurs!
! ! ! vous devez donc obtenir (get) ces valeurs pour les utiliser dans votre code.!
! ! ! La valeur de la «custom property» se substitue à la référence de la «custom property» !
! ! ! lorsque l’instruction est exécutée.!
! ! ! Par exemple si la «custom property» cpDernierAppel de la carte a pour valeur!
! ! ! «Aujourd’hui», l’instruction ci-dessus mettra les caractères «Aujourd’hui» dans le!
! ! ! champ «date».!
!
! ! ! Si une «custom property» n’existe pas sera évaluée comme empty (vide). Par!
! ! ! exemple si la carte (card) courante n’a pas de «custom property» du nom de!
! ! ! cpDernierAppel, l’instruction donnée en exemple ci-dessus videra (empty) le!
! ! ! champ «date».!
!
! ! ! La propriété customKeys d’un objet liste les «custom properties» de cet objet, une !
! ! ! par ligne :!
!
! ! ! put the customKeys of btn 1 into fld “fldCustomProps“!
!
! ! ! Pour savoir si une «custom property» existe dans un objet, il suffit de vérifier si cette !
! ! ! «custom property» est présente dans les customKeys de l’objet.!
! ! ! L’instruction suivante vérifie si un «player» possède une «custom property» nommée!
! ! ! cpToutJouer :!
!
! ! ! if cpToutJouer is among the lines of the customKeys of \
player “monPlayer“ then...
!
Nota : faire référence à une «custom property» n’existant pas n’entraîne pas d’erreur!
! ! ! de script. Cela signifie que si vous avez mal orthgraphié le nom de la «custom!
! ! ! property» dans un «handler» vous n’obtiendrez pas de message d’erreur ce qui peut!
! ! ! entraîner un problème lors du débugage.!
!
! ! ! Vous pouvez également regarder la liste des «custom properties» dans le panel!
! ! ! «Custom Properties» dans l’inspector de l’objet (cf. § 11.01.03 ci-avant).!
!
! 11.02.! Utilisation avancées des «custom properties»!
!
! ! 11.02.01.! Stocker un fichier dans une «custom property»!
!
! ! ! Vous pouver utiliser une adresse universelle (URL) pour stocker le contenu d’un!
! ! ! fichier dans une «custom property», par exemple :!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 6

!
! ! ! set the cpFichierStocké of stack “stkPile“ to \
URL “binfile:monimage.jpg“!
!
! ! ! Pour restaurer le fichier, vous placez la valeur de la «custom property» dans l’adresse!
! ! ! universelle (URL) :!
!
! ! ! put the cpFichierStocké of stack “stkPile“ into \
URL “binfile:monimage.jpg“!
!
! ! ! Parce qu’une «custom property» peut contenir n’importe quelle sorte de données,!
! ! ! vous pouvez y stocker aussi bien des fichiers texte que des fichiers binaires.!
! ! ! Vous pouvez vous servir de cette fonctionnalité pour regrouper des fichiers!
! ! ! multimédia ou d’autres types de fichiers dans vos piles.!
!
! ! ! Astuce : pour gagner de la place, compressez le fichier avant de le stocker :!
!
! ! ! set the cpFichierStocké of stack “stkPile“ to \
compress(URL “binfile:monimage.jpg“)
!
! ! ! lors de la restauration du fichier, il convient de d’abord le décompresser :!
!
! ! ! put decompress(the cpFichierStocké of stack “stkPile“ \
into URL “binfile:monimage.jpg“
!
! ! 11.02.02.!Stocker une pile (stack) dans une «custom property»!
!
! ! ! Comme nous l’avons vu ci-dessus, il est possible de stocker toutes sortes de!
! ! ! données dans une «custom property». Cette fonctionnalité très puissante va jusqu’à!
! ! ! permettre de stocker une pile entière dans la «custom property» d’un autre «stack»!
! ! ! ou d’un objet de ce «stack».!
!
! ! ! À titre d’exemple nous prendrons la création d’un «popover» (Mac OS X) de réglage!
! ! ! attaché à un contrôle personnalisé (cf. image ci-dessous) : un «double slider»!
! ! ! permettant de délimiter visuellement 2 valeurs limites (une valeur minimale et une!
! ! ! valeur maximale) :!
!
! ! ! !
!
! ! ! Pour créer la forme générale du «popover», il convient de créer cette forme à la!
! ! ! dimension voulue dans un logiciel de dessin tel que Photoshop ou Pixelmator (le!
! ! ! fond importe peu, seul le découpage extérieur sera pris en compte) :!
!

! ! ! !
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 7

! ! ! Donnez un nom à cette forme qui doit être un fichier image au format «png», par!
! ! ! exemple : «imgFormePopoverDoubleSlider.png»!
!
! ! ! Créez ensuite votre «stack» contenant tous les contrôles que vous souhaitez voir y!
! ! ! figurer et le code afférent. Les dimensions du «stack» devront être égales aux!
! ! ! dimensions de la forme précédemment créée.!
! ! ! Nommons ce stack : «stkModèlePopoverDoubleThumbSlider.livecode»!
!
! ! ! Importez dans votre «stack» «stkModèlePopoverDoubleThumbSlider.livecode»!
! ! ! l’image créée «imgFormePopoverDoubleSlider.png» à l’aide du menu File > Import!
! ! ! As Control. Supposons que LiveCode attribue à cette image l’id 1057.!
!
! ! ! Réglez alors votre «stack» «stkModèlePopoverDoubleThumbSlider.livecode» de!
! ! ! telle sorte qu’il prenne la forme de l’image importée : attribuez au champ!
! ! ! «windowShape» la valeur 1057 correspondant à l’image (forme) importée :!
!

! ! ! !
! ! ! À ce moment le stack nouvellement créé devrait ressembler (en supposant que les!
! ! ! contrôles soient identiques) à l’image ci-dessous :!
!

! ! ! !
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 8

! ! ! Venons-en maintenant à la partie intéressant plus précisément la «custom property».!

!
! ! ! D’un côté vous avez votre contrôle (ou tout autre objet) faisant partie d’un «stack»!
! ! ! A, de l’autre un «stack» B nommé «stkModèlePopoverDoubleThumbSlider.livecode»!
! ! ! ayant l’aspect de l’image ci-dessus.!
! ! ! Le but de l’opération qui suit est d’intégrer le «stack» B dans la «custom property»!
! ! ! d’un objet (pour notre exemple : contrôle personnalisé «double slider») du «stack» A.!
! ! ! L’intérêt à ce que le «stack» B soit attaché à l’objet plutôt qu’au «stack» A dans notre!
! ! ! exemple est que le «stack» B (popover de réglage) sera automatiquement copié en!
! ! ! même temps que l’objet en cas de copie de celui-ci.!
!
! ! ! Pour intégrer le «stack» B en tant que «custom property» au contrôle faisant partie!
! ! ! du «stack» A, il suffit d’entrer cette (unique) ligne de code dans la «Message Box» :!
! set the cpPopoverRéglages of group id 1020 to url
"binFile:/Développement/Développements Mac/Interface/
rmTools/stkModèlePopoverDoubleThumbSlider"
!
cpPopoverRéglages étant le nom de la «custom property» créée.
group id 1020 étant la référence (qui sera sans doute différente dans votre cas!
! ! ! car automatiquement créée par LiveCode lors de la création de l’objet ou du!
! ! ! groupe) du contrôle personnalisé «double slider»).!
! ! ! Développement/Développements Mac/Interface/rmTools étant le!
! ! ! chemin d’accès au «stack» «stkModèlePopoverDoubleThumbSlider.livecode», chemin !
! ! ! qui sera évidemment différent dans votre cas.!
!
! ! ! La «custom property» est désormais créée dans le contrôle personnalisé sous une!
! ! ! forme textuelle (exemple créé avec LiveCode 5.5) :!
!

! ! ! !
! ! ! Pour appeler le «popover» il suffit d’entrer cette instruction dans votre code à!
! ! ! l’endroit approprié :!
! go stack the cpPopoverRéglages of me
ou bien
go stack the cpPopoverRéglages of the owner of me
selon la structure de l’objet (bouton, champ ou groupe...)!
!
! ! ! LiveCode construira alors automatiquement le «stack» contenu dans la «custom!
! ! ! property».!
! ! ! !
! ! ! Cette fonctionnalité très puissante (et très rapide) ouvre des possibilités immenses!
! ! ! quant à l’utilisation des «custom properties» dans le cadre de la création d’interfaces!
! ! ! complexes.!
!
! 11.03.! Relier «handlers» et «custom properties»
!
! ! Lorsque vous modifiez une «custom property» ou lorsque vous demandez la valeur d’une!
! ! «custom property», LiveCode envoie un «trigger» setProp à l’objet dont la «custom property» a !
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 9

! ! été modifiée ou envoie un appel getProp à l’objet dont la «custom property» a été modifiée.!
! ! Pour interagir avec ces modifications ou demandes de valeur, vous pouvez écrire un «handler» !
! ! setProp pour intercepter le «trigger» ou un «handler» getProp pour intercepter l’appel.!
!
! ! Utiliser des «handlers» getProp et setProp vous permet de :!
! ! –!valider la valeur d’une «custom property» avant de la régler,!
! ! –!retourner la valeur d’une «custom property» dans un format différent de celui dans lequel!
! ! ! cette «custom property» est stockée,!
! ! –!s’assurer de la cohérence d’une collection de «custom properties» en les réglant toutes d’un!
! ! ! seul coup,!
! ! –!modifier le comportement d’un objet lorsqu’une «custom property» est modifiée.!
!
! ! Vous pouvez inclure dans un script autant de «handlers» setProp ou getProp pour autant de!
! ! «custom properties» que vous le souhaitez.!
!
! ! Nota : les «triggers» setProp et les appels getProp ne sont pas envoyés lorsqu’une propriété!
! ! intégrée est modifiée ou que l’on demande à accéder à sa valeur, ces déclenchements ne!
! ! concernent que les «custom properties».!
!
! ! 11.03.01.! Répondre au changement de la valeur d’une «custom property»!
!
! ! ! Lorsque vous modifiez une «custom property», LiveCode envoie un «trigger» setProp !
! ! ! à l’objet dont la «custom property» a été modifiée. Vous pouvez écrire un «handler»!
! ! ! setProp pour intercepter ce «trigger» pour interagir avec cette modification de!
! ! ! «custom property» et placer de «handler» où vous le souhaitez dans la hiérarchie des!
! ! ! messages (message path) utilisé par le trigger à l’instar des messages.!
!
! ! ! Structure d’un «handler» setProp!
!
! ! ! Contrairement à un «handler» interceptant un message, un «handler» interceptant!
! ! ! un «trigger» setProp débute par le mot setProp en lieu et place du mot on suivi par !
! ! ! le nom du «handler» qui est identique à celui de la «custom property» et du !
! ! ! paramètre représentant la nouvelle valeur de la «custom property».!
! ! ! Comme tous les autres «handlers», un «handler» setProp se termine par le mot end!
! ! ! suivi du nom de la «custom property».!
!
! ! ! L’exemple suivant montre un «handler» setProp pour une «custom property» nommée !
! ! ! cpPercentused qui doit être placée dans le script de l’objet lié à la «custom!
! ! ! property» :!
!
! setProp cpPercentused vpNewamount
if vpNewamount is not a number or \
vpNewamount < zero or vpNewamount > 100 then
beep 2
exit cpPercentused
end if
pass cpPercentused
end cpPercentused
!
! ! ! Lorsque vous modifiez (set) la «custom property» cpPercentused, le «handler»!
! ! ! cpPercentused sera exécuté :!
!
! ! ! set the cpPercentused of scrollbar “Progress“ to 90!
!
! ! ! Quand cette instruction est exécutée, LiveCode envoie un «trigger» setProp au!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 10

! ! ! «scrollbar». La nouvelle valeur 90 est placée dans le paramètre vpNewamount.

Le «handler» vérifie si la nouvelle valeur est bien comprise entre 0 et 100, dans le!
! ! ! cas contraire, il émettra 2 bips et empêchera la valeur de la «custom property»!
! ! ! d’être modifiée.!
!
! ! ! Pour plus de détails sur la structure setProp, reportez-vous au dictionnaire !
! ! ! LiveCode à l’entrée setProp.!
!
! ! ! Déclencher un «trigger» setProp!
!
! ! ! Lorsque le «trigger» setProp atteint le moteur LiveCode, dernier stade du «message!
! ! ! path», la «custom property» est activée. Si le «trigger» est stoppé avant d’atteindre le!
! ! ! moteur la «custom property» n’est pas activée.!
! ! ! Pour permettre au «trigger» de progresser dans le «message path» vous devez utiliser !
! ! ! l’instruction pass. L’instruction pass stoppe l’exécution du «handler» courant et!
! ! ! envoie le «trigger» vers l’objet suivant dans le «message path» comme si l’objet!
! ! ! n’avait pas de «handler» lié à la «custom property».!
!
! ! ! Dans le «handler» cpPercentused ci-avant, si le paramètre vpNewamount se!
! ! ! trouve être hors limites, le handler utilise l’instruction exit pour stopper son!
! ! ! exécution, dans le cas contraire, il exécutera l’instruction pass. Si le paramètre!
! ! ! vpNewamount se trouve être dans la fourchette de valeurs admises, l’instruction!
! ! ! pass permet à la «custom property» d’être modifiée (set), sinon, étant donné que!
! ! ! le «trigger» n’est pas transmis au moteur LiveCode, la «custom property» ne sera pas!
! ! ! modifiée.!
!
! ! ! Vous pouvez utiliser cette fonctionnalité pour vérifier la valeur de n’importe quelle!
! ! ! «custom property» avant qu’elle ne soit modifiée. Par exemple, si la valeur d’une!
! ! ! «custom property» est supposée être booléenne (true ou false), un «handler»!
! ! ! setProp pourra intercepter le «trigger» si la valeur est différente de true ou de!
! ! ! false.!
! setProp cpMonbooléen vpNouvellevaleur
if vpNouvellevaleur is true or vpNouvellevaleur is false
then pass cpMonbooléen
exit cpMonbooléen!
!
! ! ! Utiliser le «message path» avec un déclenchement setProp!
!
! ! ! Étant donné que les «triggers» setProp utilisent le «message path», un simple objet!
! ! ! peut recevoir les «triggers» setProp pour tous les objets qu’il contient. Par exemple!
! ! ! les «triggers» setProp concernant les contrôles d’une carte («card») sont envoyés à la!
! ! ! carte («card») si les scripts des contrôles ne contiennent pas de «handler» pour cette!
! ! ! «custom property».!
!
! ! ! Attention : si un «handler» setProp modifie (set) la «custom property» à laquelle il est!
! ! ! dédié alors qu’un objet n’a pas ce «handler» dans son «message path» une boucle!
! ! ! perpétuelle se produira. Pour éviter cela il convient de régler la valeur de la!
! ! ! propriété lockMessages sur true avant de modifier la valeur de la «custom!
! ! ! property».!
!
! ! ! Supposons par exemple que toutes les ca!rtes de votre «stack» ont une «custom!
! ! ! property» nommée cpDernièremodification. Au lieu de mettre un «handler»!
! ! ! setProp relié à cette «custom property» dans le script de chaque carte («card») vous!
! ! ! pouvez prévoir uniquement un «handler» dans le script de votre «stack» :!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 11

!
! ! ! setProp cpDernièremodification vpNouvelledate
convert vpNouvelledate to seconds
lock messages -- évite la boucle perpétuelle
set the cpDernièremodification of the target to vpNouvelledate
unlock messages
end cpDernièremodification!
!
! ! ! Nota : pour faire référence à l’objet pour lequel la «custom property» est définie,!
! ! ! utilisez la fonction target. Target fait référence à l’objet qui reçoit en premier!
! ! ! le «trigger» setProp même si le «handler» en phase d’exécution est dans le script d’un!
! ! ! autre objet.!
! ! ! ! !
! ! ! Régler des «custom properties» avec un «handler» setProp!
!
! ! ! Dans l’exemple cpDernièremodification ci-avant, le «handler» modifie (set)!
! ! ! directement la «custom property» au lieu de passer simplement le «trigger» setProp.!
! ! ! Vous devez utiliser cette méthode si le «handler» opère un changement de la valeur!
! ! ! de la «custom property» car l’instruction pass passe uniquement la valeur initiale!
! ! ! de la «custom property».!
!
! ! ! Important : si vous utilisez la commande set dans un «handler» setProp pour!
! ! ! modifier (set) la même «custom property» de l’objet courant, aucun «trigger» setProp!
! ! ! ne sera envoyé à l’objet courant de manière à éviter la création d’une boucle!
! ! ! perpétuelle. Lorsque vous définissez (set) une autre «custom property», LiveCode!
! ! ! envoie un «trigger» setProp ce qui provoque le déclenchement du «handler» dédié à la !
! ! ! «custom property» pour un objet autre que celui dont le script contient le «handler»!
! ! ! setProp.!
!
! ! ! En utilisant cette méthode vous pouvez non seulement vérifier la valeur de la!
! ! ! «custom property», l’autoriser à être modifiée (set) non seulement si la plage de!
! ! ! valeur est respectée, mais aussi si, par exemple, le format est correct et ainsi de!
! ! ! suite pour d’autres conditions.!
!
! ! ! L’exemple suivant est similaire au «handler» cpPercentused ci-avant mais avec!
! ! ! l’adjonction d’un signal sonore si la valeur du paramètre vpNewamount n’est pas!
! ! ! comprise dans la plage de valeur autorisée. Le «handler» force la nouvelle valeur à!
! ! ! entrer dans la plage allant de 0 à 100.!
!
! ! ! setProp cpPercentused vpNewamount
set the cpPercentused of the target to \
max(zero,min(100, vpNewamount))
end cpPercentused!
!
! ! ! «Custom property» inexistante!
!
! ! ! Si la «custom property» dont il est fait référence dans un «handler» setProp n’existe!
! ! ! pas, le «handler» setProp est tout de même exécuté lorsque un «handler» modifie (set) !
! ! ! la «custom property». Lorsque le «handler» envoie le setProp «trigger» dans ce cas la!
! ! ! «custom property» est créée.!
!
! ! 11.03.02.! Répondre à une requête concernant la valeur d’une «custom property»!
!
! ! ! Lorsque vous demandez la valeur d’une «custom property», LiveCode envoie un!
! ! ! appel getProp à l’objet dont la «custom property» a été modifiée. Vous pouvez écrire!
! ! ! un «handler» getProp pour intercepter cet appel pour interagir avec cette!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 12

! ! ! modification de «custom property» et placer de «handler» où vous le souhaitez dans!

! ! ! la hiérarchie des messages (message path) utilisé par l’appel à l’instar des messages.!
!
! ! ! Structure d’un «handler» getProp!
!
! ! ! Contrairement à un «handler» interceptant un message, un «handler» interceptant!
! ! ! un «trigger» getProp débute par le mot getProp en lieu et place du mot on suivi!
! ! ! par le nom du «handler» qui est identique à celui de la «custom property».!
! ! ! Comme tous les autres «handlers», un «handler» getProp se termine par le mot end!
! ! ! suivi du nom de la «custom property».!
!
! ! ! L’exemple suivant montre un «handler» getProp pour une «custom property»!
! ! ! nommée cpPercentused qui doit être placée dans le script de l’objet lié à la!
! ! ! «custom property» :!
!
! getProp cpPercentused
global vpLastTimeAccess
put the seconds into vpLastTimeAccess
pass cpPercentused
end cpPercentused
!
! ! ! Lorsque vous modifiez (set) la «custom property» cpPercentused, le «handler»!
! ! ! cpPercentused sera exécuté :!
!
! ! ! set the cpPercentused of card 1 into vlVariable!
!
! ! ! Quand cette instruction est exécutée, LiveCode envoie un «trigger» getProp à la!
! ! ! carte de manière à obtenir la valeur vpLastTimeAccess de la «custom property» !
! ! ! cpPercentused. Le «handler» ci-dessus enregistre la date et l’heure actuelle!
! ! ! dans une variable globale nommée vpLastTimeAccess avant que la «custom!
! ! ! property» cpPercentused soit évaluée!
!
! ! ! Pour plus de détails sur la structure getProp, reportez-vous au dictionnaire !
! ! ! LiveCode à l’entrée getProp.!
!
! ! ! Retourner une valeur depuis un «handler» getProp!
!
! ! ! Lorsque le «trigger» getProp atteint le moteur LiveCode, dernier stade du «message!
! ! ! path», LiveCode obtient (get) la valeur de la «custom property» de l’objet et!
! ! ! remplace cette valeur dans l’expression dans laquelle la «custom property» est!
! ! ! utilisée!
! ! ! Pour permettre au «trigger» de progresser dans le «message path» vous devez utiliser !
! ! ! l’instruction pass. L’instruction pass stoppe l’exécution du «handler» courant et!
! ! ! envoie le «trigger» vers l’objet suivant dans le «message path» comme si l’objet!
! ! ! n’avait pas de «handler» lié à la «custom property».!
!
! ! ! Pour utiliser une valeur différente de celle stockée dans la «custom property» (si!
! ! ! vous souhaitez, par exemple, reformater la valeur initiale) vous devez faire usage de!
! ! ! l’instruction return à la place de l’instruction pass.!
!
! ! ! L’exemple suivant est un handler getProp faisant référence à une «custom property»!
! ! ! nommée cpDernierChangement qui contient une date exprimée en secondes :!
! getProp cpDernierChangement
get the cpDernierChangement of the target
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 13

convert it to long date

end cpDernierChangement
!
L’instruction de contrôle return, lorsqu’elle est utilisée dans un «handler» getProp,!
! ! ! renvoie la valeur de la «custom property» au handler qui en fait la requête. Dans!
! ! ! l’exemple ci-dessus, c’est la date convertie et non la valeur brute en secondes!
! ! ! conservée dans la «custom property» qui est retournée au «handler».!
!
! ! ! Important : si vous utilisez la valeur contenue dans une «custom property» dans un!
! ! ! «handler» getProp, aucun message getProp n’est envoyé à l’objet cible (target), ceci!
! ! ! permet d’éviter la création d’une boucle perpétuelle dans laquelle le «handler»!
! ! ! getProp s’appellerait lui-même.!
!
! ! ! Un «handler» peut soit utiliser l’instruction de contrôle return pour renvoyer une!
! ! ! valeur soit utiliser l’instruction de contrôle pass pour permettre à LiveCode!
! ! ! d’obtenir (get) la valeur contenue dans la «custom property».!
!
! ! ! Dans le cas où un message getProp est intervepté avant d’atteindre le moteur!
! ! ! LiveCode aucune valeur n’est retournée vers le «handler» getProp, dans ce cas la!
! ! ! «custom property» renvoie la valeur empty (vide). En d’autres termes, un «handler» !
! ! ! getProp doit comprendre soit une instruction de contrôle return soit une!
! ! ! instruction de contrôle pass sinon la valeur retournée sera toujours vide (empty).!
!
! ! ! Utiliser le «message path» avec un appel getProp!
!
! ! ! Étant donné que les appels getProp utilisent le «message path», un simple objet!
! ! ! peut recevoir les appels getProp pour tous les objets qu’il contient. Par exemple!
! ! ! les appels getProp concernant les contrôles d’une carte («card») sont envoyés à la!
! ! ! carte («card») si les scripts des contrôles ne contiennent pas de «handler» pour cette!
! ! ! «custom property». Vous pouvez profiter du «message path» pour utiliser le même!
! ! ! appel getProp pour tous les objets ayant le même «custom property».!
!
! ! ! «Custom property» inexistante!
!
! ! ! Si la «custom property» dont il est fait référence dans un «handler» getProp n’existe!
! ! ! pas, le «handler» getProp est tout de même exécuté lorsque la «custom property» est!
! ! ! mentionnée dans une expression. la «custom property» retourne la valeur empty si!
! ! ! bien que demander la valeur d’une «custom property» n’existant pas ne déclenche!
! ! ! pas d’erreur de script.!
!
! 11.04.! Ensemble de «custom properties» (custom property sets)!
!
! ! 11.04.01.!Qu’est-ce qu’un ensemble de «custom properties» ?!
!
! ! ! Une ou plusieurs «custom properties» font partie d’ensembles de «custom!
! ! ! properties» ou «custom property sets» ou en tableaux (arrays) de «custom!
! ! ! properties».!
! ! ! Un ensemble de «custom properties» ou «custom property set» est un groupe de!
! ! ! «custom properties» portant le nom que vous lui avez attribué.!
!
! ! ! Lorsque vous faites référence à une «custom property», LiveCode cherche cette!
! ! ! propriété dans l’ensemble de «custom properties» de l’objet actif. Lorsque vous!
! ! ! créez une «custom property» ou définissez (set) une «custom property», LiveCode!
! ! ! crée ou définit la valeur de celle-ci dans l’ensemble de «custom properties»!
! ! ! actuellement actif.!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 14

! ! ! Un ensemble de «custom properties» ou «custom property set» est actif à tout!

! ! ! moment. Vous pouvez utiliser la syntaxe propre aux tableaux (arrays) pour obtenir!
! ! ! (get) ou définir (set) la ou les valeurs de «custom properties» autres que celle!
! ! ! actuellement active.!
!
! ! ! Les exemples présentés dans les chapitres précédents partent du principe que vous!
! ! ! n’ayez pas créé d’ensembles de «custom properties» ou «custom property sets».!
! ! ! Lorsque vous créez une «custom property» sans créer un ensemble de «custom!
! ! ! properties» ou «custom property set» pour celle-ci comme dans les exemples!
! ! ! précédents, la «custom property» nouvellement créée devient par défaut un élément!
! ! ! de l’ensemble de «custom property» ou «custom property set» de l’objet.!
!
! ! ! Une des utilisations la plus fréquente d’un ensemble de «custom properties» ou!
! ! ! «custom property set» est de permettre la traduction des étiquettes et autres!
! ! ! chaînes de caractères de l’application dans d’autres langues. Vous pouvez ainsi avoir!
! ! ! des ensembles de «custom properties» ou «custom property sets» nommés !
! ! ! csAnglais et csAllemand en plus de la propriété customKeys par défaut!
! ! ! définissant la langue de base de l’application (le français en l’occurence), des!
! ! ! handlers setProp et getProp dans les autres ensembles de «custom properties» ou!
! ! ! «custom property sets» traitant les différences linguistiques.!
!
! ! 11.04.02.!Comment créer un ensemble de «custom properties» ?!
!
! ! ! Pour rendre actif un ensemble de «custom properties» ou «custom property set»!
! ! ! vous devez définir la propriété customPropertySet de l’objet.!
! ! ! Comme pour les «custom properties» et les variables locales, si l’ensemble de!
! ! ! «custom properties» ou «custom property set» auquel vous faites référence n’existe!
! ! ! pas, il sera automatiquement créé par LiveCode.!
!
! ! ! La ligne de code suivante crée un ensemble de «custom properties» ou «custom!
! ! ! property set» nommé csAlternatif pour un objet et rend cet ensemble actif :!
!
! ! ! set the customPropertySet of the target to “csAlternatif“!
!
! ! ! Vous pouvez également afficher, créer et supprimer les ensembles de «custom!
! ! ! properties» ou «custom property sets» depuis le panel «Custom properties» de!
! ! ! l’inspecteur.!
!
! ! ! Vous pouvez lister tous les ensembles de «custom properties» ou «custom property!
! ! ! sets» d’un objet en utilisant la propriété customPropertySets.!
!
! ! ! Comme pour les «custom properties» vous pouvez créer des ensembles de «custom!
! ! ! properties» ou «custom property sets» pour tout objet, toutefois, il n’est pas!
! ! ! possible de créer d’ensemble global (comparable à une variable globale) de «custom!
! ! ! properties» ou «custom property sets» ni pour une chaine de caractères d’un champ!
! ! ! («chunk of field»).!
!
! ! 11.04.03.!Comment supprimer un ensemble de «custom properties» ?!
!
! ! ! Supprimer un ensemble de «custom properties» suit le même processus que la!
! ! ! suppression d’une «custom property» comme vu précédemment au § 11.01.04.!
!
! ! ! LiveCode ne dispose pas de commande permettant la suppression d’une «custom!
! ! ! property». Néanmoins, si vous placez tous les noms des ensembles «custom!
! ! ! properties» ou «custom property sets» dans une variable, vous pouvez supprimer le!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 15

! ! ! nom de celle dont vous ne voulez plus dans cette variable ; il vous suffit alors de!
! ! ! mettre à jour la liste des noms des «custom properties» à l’aide de la propriété!
! ! ! customPropertySets attachée aux «custom properties» de l’objet.!
!
! ! ! Par exemple, le script qui suit a pour effet de supprimer un ensemble de «custom!
! ! ! properties» ou «custom property set» nommée csMonEnsemble attaché au!
! ! ! bouton btnBouton :!
!
! ! get the customPropertySets of btn “btnBouton“
set the wholeMatches to true
delete line lineOffset(“csMonEnsemble “,it) of it
set the customPropertySets of btn “btnBouton“ to it!
!
! ! ! Vous pouvez également supprimer un ensemble de «custom properties» ou «custom!
! ! ! property set» depuis le panel «Custom Properties» dans l’inspector de l’objet :!
! ! ! sélectionnez l’ensemble de «custom properties» ou «custom property set» à!
! ! ! supprimer (dans cet exemple : csEnsembleCP) :!
!
! ! ! !

! ! ! !
!
! ! ! puis cliquez sur l’icône de suppression .!
!
! ! 11.04.03.!Référence à un ensemble de «custom properties»!
!
! ! ! Voici quelques lignes de code illustrant l’exemple évoqué à la fin du § 11.04.01!
! ! ! ci-avant :!
!
! ! ! set the customPropertySet of this stack to “csEspagnol“!
!
! ! ! Ce code rend actif l’ensemble de «custom properties» ou «custom property set» !
! ! ! nommé csEspagnol. Comme vous ne pouvez avoir qu’un seul ensemble de!
! ! ! «custom properties» ou «custom property set» actif à la fois pour chacun des objets!
! ! ! de l’application, désormais, chaque référence à une «custom property» de cet objet!
! ! ! pointera sur la valeur contenue dans l’ensemble de «custom properties» ou «custom!
! ! ! property set» actif.!
!
! ! ! Dans ce même exemple, pour revenir à la langue de base de l’application (le!
! ! ! français), il suffit d’utiliser le code suivant :!
!
! ! ! set the customPropertySet of this stack to empty
!
Si vous faites référence à une «custom property» ne faisant pas partie de l’ensemble!
! ! ! (custom property set) actif, LiveCode retournera la valeur empty.!
! ! ! Si vous attribuez une valeur à une «custom property» ne faisant pas partie de!
! ! ! l’ensemble (custom property set) actif, LiveCode créera cette «custom property»!
! ! ! dans l’ensemble (custom property set) actif. Vous pouvez donc avoir deux «custom!
! ! ! properties» portant le même nom mais situées dans deux ensembles (custom!
! ! ! property set) distincts, une modification de l’une des deux n’affectera pas l’autre.!
!
! ! ! La propriété customProperties d’un objet n’inclut uniquement que les «custom!
! ! ! properties» présentes dans l’ensemble de «custom properties» (custom property set)!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 16

! ! ! actif. Pour faire référence à la propriété customProperties d’un ensemble de!

! ! ! «custom properties» (custom property set) spécifique vous devez préciser le nom de!
! ! ! l’ensemble entre crochets :!
!
! ! ! put the customProperties[csEnsemble] of this card into vtTableau
!
La propriété customProperties d’un objet présente les ensembles de «custom!
! ! ! properties» (custom property sets) sous forme de liste, un ensemble par ligne :!
!
! ! ! answer the customPropertySets of field “fldChamp“!
!
! ! ! ce qui n’est pas le cas lorsque vous accédez à cette propriété par l’intermédiaire de!
! ! ! l’inspecteur.!
!
! ! ! Pour savoir si un ensemble de «custom properties» (custom property set) existe,!
! ! ! vous devez vérifier s’il est présent dans la propriété customPropertySets de!
! ! ! l’objet. L’exemple suivant vérifie si une image a une «custom property» nommée!
! ! ! cpEspagnol :!
!
! ! ! if “cpEspagnol“ is among the lines of the \
customPropertySets of image id 23945 then...!
!
! ! 11.04.04.!Ensemble de «custom properties» par défaut!
!
! ! ! L’ensemble de «custom properties» (custom property set) par défaut d’un objet est!
! ! ! l’ensemble actif si vous n’avez pas utilisé la propriété customPropertySet pour!
! ! ! modifier le réglage par défaut. Chaque objet possède un ensemble de «custom!
! ! ! properties» (custom property set) par défaut, vous n’avez pas besoin d’en créer un.!
!
! ! ! Lorsque vous créez une «custom property» sans apporter de modification!
! ! ! d’affectation à un ensemble, elle appartiendra à l’ensemble de «custom!
! ! ! properties» (custom property set) par défaut. Si vous n’apportez pas de modification !
! ! ! à la propriété customPropertySet, toutes les «custom properties» que vous!
! ! ! créerez dans l’ensemble de «custom properties» (custom property set) par défaut.!
!
! ! ! l’ensemble de «custom properties» (custom property set) par défaut n’à pas de nom!
! ! ! et n’apparait pas dans la liste affichée par la propriété customPropertySets de!
! ! ! l’objet. Pour revenir à l’ensemble par défaut depuis un autre ensemble, il suffit!
! ! ! d’affecter la valeur empty à la propriété customPropertySet de l’objet :!
!
! ! ! set the customPropertySet of the target to empty!
!
! ! 11.04.05! Copier des «custom properties» entre ensembles de «custom properties»!
!
! ! ! La valeur d’un ensemble de «custom properties» (custom property set) lorsqu’il est!
! ! ! créé est vide (empty) cela veut dire qu’il ne contient aucune «custom property».!
! ! ! Vous insérez des «custom properties» dans un nouvel ensemble de «custom!
! ! ! properties» (custom property set) en créant ces «custom properties» lorsque que cet!
! ! ! ensemble est actif :!
! -- création du nouvel ensemble
set the customPropertySet of this stack to “csTexteFrancais“
-- copie des «custom properties» depuis l’ensemble Anglais
-- vers le nouvel ensemble Français
set the customProperties[“csTexteFrancais“] of this stack \
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 17

to the customProperties[“csTexteAnglais“] of this stack

!
Attention : l’environnement de développement de LiveCode utilise des «custom!
! ! ! properties» pour créer sa propre interface. Toutes ces «custom properties» sont!
! ! ! stockées dans des ensembles de «custom properties» (custom property sets) dont les !
! ! ! noms débutent par le préfixe «cRev».!
! ! ! Si vous créez des «custom properties» sans toutefois les organiser dans des!
! ! ! ensembles de «custom properties» (custom property sets) vous n’avez pas à vous!
! ! ! soucier des «custom properties» propres à LiveCode. Dans le cas où vous modifiez!
! ! ! la propriété customPropertySet d’un objet, vos handlers ne doivent en aucun cas!
! ! ! interagir avec les «custom properties» propres à LiveCode.!
! ! ! Toutefois si vous utilisez des ensembles de «custom properties» (custom property!
! ! ! sets), par exemple si vous avez dans votre code une boucle repeat passant en revue!
! ! ! les ensembles de «custom properties» (custom property sets) d’un objet,!
! ! ! assurez-vous de n’utiliser aucun nom de «custom property» débutant par le préfixe!
! ! ! cRev de manière à ne pas interférer accidentellement avec les «custom properties»!
! ! ! propres à LiveCode.
!
! ! 11.04.06.!Ensembles de «custom properties» et «handlers» setProp!
!
! ! ! Un «handler» setProp pour un ensemble de «custom properties» (custom property!
! ! ! set) se comporte différemment d’un «handler» setProp d’une «custom property» se!
! ! ! trouvant dans l’ensemble par défaut.!
!
! ! ! Lorsque vous utilisez la valeur d’une «custom property» dans un ensemble de!
! ! ! «custom property» (custom property set), l’appel getProp est nommé pour!
! ! ! l’ensemble et non pour la «custom property». Le nom de la propriété est passé en!
! ! ! tant que paramètre selon une syntaxe spéciale. Cela signifie que pour une «custom!
! ! ! property» d’un ensemble, vous écrivez un seul «handler» getProp pour l’ensemble!
! ! ! plutôt qu’un «handler» pour chacune des «custom properties».!
!
! ! ! L’exemple suivant traite des «triggers» setProp pour toutes les «custom properties»!
! ! ! d’un ensemble de «custom properties» (custom property set) nommé!
! ! ! csTexteFrancais contenant des «custom properties» nommées!
! ! ! cpMessageErreurStandard, cpFichierMessage et sans doute d’autres!
! ! ! «custom properties : !
!
! ! ! setProp csTexteFrancais[cpNomPropriété] vpNouvelleValeur
-- le paramètre cpNomPropriété contient le nom de la
-- custom property à régler
switch cpNomPropriété
case “cpMessageErreurStandard“
set the csTexteFrancais[“cpMessageErreurStandard“] \
of the target to return & vpNouvelleValeur & return
exit csTexteFrancais
break
case “cpFichierMessage“
set the csTexteFrancais[“cpFichierMessage “] \
of the target to return & vpNouvelleValeur & return
exit csTexteFrancais
break
default
pass csTexteFrancais
end switch
end csTexteFrancais
!
Comme vous pouvez le remarquer dans les instructions de contrôle exit, pass et!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 18

! ! ! end, le nom du handler setProp est le même que celui de l’ensemble de «custom!
! ! ! property» (custom property set) qu’il contrôle : csTexteFrancais. Parce qu’il n’y !
! ! ! a qu’un seul «handler» pour toutes les «custom properties» composant l’ensemble!
! ! ! (custom property set), le «handler» utilise l’instruction de contrôle switch pour!
! ! ! effectuer une action différente pour chacune des «custom properties» concernées.!
!
! ! ! Supposons que vous changiez la «custom property» cpMessageErreurStandard :!
!
! ! ! set the customPropertySet of this stack to “csTexteFrancais“
set the cpMessageErreurStandard of this stack to field 1

LiveCode envoie un «trigger» setProp au «stack» ce qui conduit à l’exécution du!

! ! ! «handler» ci-avant.!
! ! ! La «custom property» que vous définissez, cpMessageErreurStandard, est!
! ! ! placée dans le paramètre cpNomPropriété, et la nouvelle valeur, le contenu du!
! ! ! champ 1 (field 1) est placé dans le paramètre vpNouvelleValeur.!
! ! ! Le «handler» exécute la condition “cpMessageErreurStandard“ consistant à !
! ! ! placer un caractère retour (return) avant et après la nouvelle valeur de la!
! ! ! «custom property» avant de définir celle-ci.!
!
! ! ! Si vous définissez une autre «custom property» que cpMessageErreurStandard
ou cpFichierMessage dans l’ensemble de «custom property» (custom property!
! ! ! set) csTexteFrancais, la condition par défaut (default) est exécutée. Dans!
! ! ! ce cas l’instruction de contrôle pass permet au «trigger» setProp de cheminer dans!
! ! ! le «message path» et lorsqu’il atteint le moteur, LiveCode définit la «custom!
! ! ! property».!
!
! ! ! Nota : comme indiqué ci-dessus, vous pouvez adresser une «custom property» d’un!
! ! ! ensemble soit par la première condition du switch soit en utilisant la syntaxe!
! ! ! propre aux tableaux (arrays) pour indiquer à la fois l’ensemble de «custom!
! ! ! property» (custom property set) et la «custom property», comme dans l’exemple!
! ! ! suivant :!
!
! ! ! set the customPropertySet of me to “csEnsemble“
set the cpPropriété of me to true!
!
! ! ! est équivalent à :!
!
! ! ! set the csEnsemble[“cpPropriété“] of me to true!
!
! ! ! Peu importe la manière dont vous définissez la «custom property», si elle appartient!
! ! ! à un ensemble de «custom property» (custom property set), le «trigger» setProp doit!
! ! ! avoir le même nom que l’ensemble de «custom property» (custom property set) et!
! ! ! non celui de la «custom property» et vous devez utiliser le «handler» setProp sous la!
! ! ! forme décrite ci-avant pour intercepter le «trigger» setProp.!
!
! ! 11.04.07.!Ensembles de «custom properties» et «handlers» getProp!
!
! ! ! Un «handler» getProp pour un ensemble de «custom properties» (custom property!
! ! ! set) se comporte différemment d’un «handler» getProp d’une «custom property» se!
! ! ! trouvant dans l’ensemble par défaut.!
!
! ! ! Lorsque vous définissez une «custom property» dans un ensemble de «custom!
! ! ! property» (custom property set), le «trigger» setProp est nommé pour l’ensemble et!
! ! ! non pour la «custom property». Le nom de la propriété est passé en tant que!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 19

! ! ! paramètre selon une syntaxe spéciale. Cela signifie que pour une «custom property»!
! ! ! d’un ensemble, vous écrivez un seul «handler» setProp pour l’ensemble plutôt qu’un!
! ! ! «handler» pour chacune des «custom properties».!
!
! ! ! L’exemple suivant traite des appels getProp pour toutes les «custom properties»!
! ! ! d’un ensemble de «custom properties» (custom property set) nommé ! !
! ! ! csRéglagesExpert contenant des «custom properties» nommées!
! ! ! cpMenuFichier, cpMenuEdition et sans doute d’autres «custom properties :!
!
! ! ! Attention : si un «handler» getProp n’est pas attaché à l’objet contenant la «custom!
! ! ! property» et qu’il utilise la valeur de cette «custom property», une boucle sans fin!
! ! ! sera générée. Pour éviter ce problème il suffit de définir la propriété!
! ! ! lockMessages sur true avant de recueillir la valeur de la «custom property».!
!
! ! ! getProp csRéglagesExpert[cpNomPropriété]
-- le paramètre cpNomPropriété contient le nom de la
-- custom property à intercepter
switch cpNomPropriété
case “cpMenuFichier “
if the csRéglagesExpert[cpMenuFichier] of the \
target is empty then return “(No items“
else pass csRéglagesExpert
break
case “cpMenuEdition“
if the csRéglagesExpert[cpMenuEdition] of the \
target is empty then
return the csRéglagesDébutant[cpMenuEdition] \
of the target
else
pass csRéglagesExpert
end if
break
default
pass csRéglagesExpert
end switch
end csRéglagesExpert!
!
! Comme vous pouvez le remarquer dans les instructions de contrôle pass et end,!
! ! ! le nom du handler getProp est le même que celui de l’ensemble de «custom!
! ! ! property» (custom property set) qu’il contrôle : csRéglagesExpert. !
! ! ! Parce qu’il n’y a qu’un seul «handler» pour toutes les «custom properties» composant !
! ! ! l’ensemble (custom property set), le «handler» utilise l’instruction de contrôle!
! ! ! switch pour effectuer une action différente pour chacune des «custom properties» !
! ! ! concernées.!
!
! ! ! Supposons que vous interceptiez la «custom property» cpMenuFichier :!
!
! ! ! set the customPropertySet of btn 1 to “csRéglagesExpert “
put the cpMenuFichier of btn 1 into me

LiveCode envoie un appel getProp au bouton ce qui conduit à l’exécution du!

! ! ! «handler» ci-avant.!
! ! ! La «custom property» que vous interrogez, cpMenuFichier, est placée dans le!
! ! ! paramètre cpNomPropriété, le «handler» exécute la condition “cpMenuFichier“!
! ! ! et si la propriétéest vide (empty), il retourne : (No items.!
! ! ! Dans les autres cas l’instruction de contrôle pass permet au «trigger» getProp de!
! ! ! cheminer dans le «message path» et lorsqu’il atteint le moteur, LiveCode interroge!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 20

! ! ! la «custom property».!
!
! 11.05.! Tableaux (arrays), «custom properties» et ensembles de «custom
properties» (custom properties sets)
!
Toutes les «custom properties» composant un ensemble de «custom properties» (custom!
! ! property set) forment un tableau (array). Le nom du tableau (array) est celui de l’ ensemble!
! ! de «custom properties» (custom property set) et les éléments de ce tableau (array) sont les!
! ! «custom properties» composant cet ensemble.
!
! ! 11.05.01.! Faire référence à des «custom properties» en utilisant la syntaxe propre aux tableaux (arrays)!
!
! ! ! Vous pouvez utiliser la syntaxe propre aux tableaux (arrays) pour faire référence aux!
! ! ! «custom properties» dans n’importe quel ensemble de «custom properties» (custom!
! ! ! property set). Cela vous permet d’interroger (get) ou d’affecter (set) une valeur à!
! ! ! n’importe quelle «custom property», même si celle-ci ne se trouve pas dans!
! ! ! l’ensemble de «custom properties» (custom property set) actif, sans changer celui-ci.!
!
! ! ! Prenons, par exemple, un bouton ayant une «custom property» nommée cpProp!
! ! ! faisant partie de l’ensemble de «custom properties» (custom property set) nommé!
! ! ! csEnsemble. Si csEnsemble est l’ensemble actif vous pouvez faire référence à!
! ! ! la «custom property» cpProp comme ceci :!
!
! ! ! get the cpProp of btn 1
set the cpProp of the target to 20
!
Vous pouvez également utiliser la syntaxe propre aux tableaux (arrays) pour faire!
! ! ! référence à la «custom property» cpProp même si l’ensemble de «custom!
! ! ! properties» (custom property set) csEnsemble n’est pas l’ensemble actif :!
!
! ! ! get the csEnsemble[“cpProp“] of btn 1
set the csEnsemble[“cpProp“] of the target to 20!
!
! ! 11.05.02.! Stocker un tableau (array) dans un ensemble de «custom properties» (custom properties set)!
!
! ! ! Si vous stockez plusieurs «custom properties» dans un ensemble de «custom!
! ! ! properties» (custom property set), cet ensemble peut être utilisé comme un tableau!
! ! ! (array). Vous pouvez considérer l’ensemble de «custom properties» (custom property !
! ! ! set) comme une simple «custom property» et chaque «custom property» de cet!
! ! ! ensemble comme étant les composants d’un tableau (array).!
!
! ! ! Pour stocker un tableau (array) de variables, vtTableau, dans un ensemble de!
! ! ! «custom properties» (custom property set), utilisez le code suivant :!
!
! ! ! set the customProperties[“csEnsemble“] of me to vtTableau
!
Remarque : étant donné que l’ensemble de «custom properties» (custom property !
! ! ! set) n’a pas de nom, il n’est pas possible d’utiliser la syntaxe propre aux tableaux!
! ! ! (arrays) pour faire référence à une «custom property» contenue dans l’ensemble par!
! ! ! défaut.!
!
! ! ! Le code ci-avant crée un ensemble de «custom properties» (custom property set)!
! ! ! nommé csEnsemble et stocke chaque élément dans le tableau (array)
vtTableau en tant que «custom property» dans un nouvel ensemble. !
! ! ! Pour extraire un élément du tableau (array) utilisez le code suivant :!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 21

!
! ! ! get the csEnsemble[“vtElement“] of fld “fldExemple“
!
! 11.06.! Virtual properties (propriétés virtuelles)
!
! ! 11.06.01.!Qu’est-ce qu’une «virtual property» ?!
!
! ! ! Une «virtual property» (propriété virtuelle) est une «custom property» qui n’existe!
! ! ! que dans un «handler» setProp et/ou getProp et qui n’est jamais réellement défini.!
! ! ! Une «virtual property» n’est jamais attachée à un objet, elle est utilisée pour!
! ! ! déclencher des «handlers» setProp et getProp qui eux sont chargés de l’action à!
! ! ! mener.!
!
! ! ! Lorsque vous utilisez la commande set avec une «virtual property», son «handler»!
! ! ! setProp est exécuté mais le «trigger» setProp n’est pas transmis au moteur LiveCode si !
! ! ! bien que la «virtual property» n’est pas attachée à l’objet. Lorsque vous utilisez une!
! ! ! «virtual property» dans une expression, son «handler» getProp retourne une valeur!
! ! ! sans faire référence à l’objet. Dans les deux cas, l’utilisation d’une «virtual property»!
! ! ! entraîne simplement l’exécution d’un «handler».!
!
! ! ! Vous pouvez utiliser des «virtual properties» pour :!
! ! ! – donner à un objet un ensemble de comportements,!
! ! ! – calculer la valeur associée à un objet,!
! ! ! – intégrer une nouvelle propriété qui se comporte comme une propriété intégrée.!
!
! ! 11.06.02.!Quand utiliser une «virtual property» ?!
!
! ! ! Comme elles ne sont pas stockées dans un objet, les «virtual properties» sont!
! ! ! éphémères, c’est à dire qu’elles sont recalculées chaque fois que vous les sollicitez.!
! ! ! Lorsqu’une «custom property» dépend d’autres propriétés pouvant être définies de!
! ! ! manière indépendantes, il peut être judicieux d’utiliser une «virtual property».!
! ! ! Par exemple, le «handler» ci-dessous calcule la position courante d’une barre de!
! ! ! défilement sous forme de pourcentage (à la place d’un nombre absolu) :!
!
! ! ! getProp cvPourcentage
put the endValue of the target - the statValue \
of the target into vpValeur
return the thumbPosition of me * 100 div vpValeur
end cvPourcentage
!
La valeur de la «custom property» cvPourcentage dépend de la!
! ! ! thumbPosition de la barre de défilement qui peut changer à chaque instant (à la!
! ! ! fois par l’action de l’utilisateur ou par l’intermédiaire d’un «handler»). Pour cette!
! ! ! raison, si vous utilisez une «custom property» associée à l’objet, celle-ci devra être!
! ! ! recalculée en permanence. En utilisant une «virtual property» vous pouvez être sûr!
! ! ! que la valeur de la propriété sera toujours actualisée car le «handler» getProp la!
! ! ! recalculera chaque fois que la propriété cvPourcentage de la barre de!
! ! ! défilement sera appelée.!
!
! ! ! Les «virtual properties» peuvent également être de bonnes solutions lorsque les!
! ! ! valeurs des propriétés sont grandes. Étant donné que la valeur d’une «virtual!
! ! ! property» n’est pas stockée dans un objet, elle ne prend pas d’espace-disque et n’est!
! ! ! montée en mémoire que le temps du calcul.!
! ! ! Une autre bonne raison d’utiliser une «virtual property» est d’éviter les redondances. !
! ! ! Le «handler» suivant règle la largeur (width) d’un objet, non pas en pixels, mais!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 22

! ! ! selon le pourcentage de la largeur du «owner» de l’objet :!

!
! ! ! !
! ! ! setProp cvPourcentageLargeur vpNouveauPourcentage
set the width of the target to the width of the owner \
of the target * vpNouveauPourcentage div 100
end cvPourcentageLargeur
!
Supposons que ce «handler» soit placé dans le script d’un bouton de carte d’un stack !
! ! ! de 320 pixels de large. Si vous réglez le cvPourcentageLargeur du bouton à!
! ! ! 25, la hauteur du bouton est réglé à 80, ce qui représente 25% de la largeur du stack !
! ! ! qui est de 320 pixels. Il n’y a pas beaucoup de sens à stocker la largeur d’un objet!
! ! ! tributaire de la largeur d’un autre objet.!
!
! ! ! L’utilisation d’une «virtual property» s’impose lorsque vous souhaitez définir!
! ! ! l’attribut d’un objet et qu’il n’est pas nécessaire d’en stocker la valeur car celle-ci!
! ! ! devra être de toute façon recalculée ou parcequ’elle est trop grande pour être!
! ! ! stockée.!
!
! ! 11.06.03.!«Handlers» pour une «virtual property»!
!
! ! ! Comme vous avez pu voir dans l’exemple ci-dessus, un «handler» lié à une «virtual!
! ! ! property» est structuré de la même manière qu’un «handler» pour n’importe quelle!
! ! ! autre «custom property». La seule différence, dès lors que le «handler» a tout ce dont !
! ! ! il a besoin, est qu’il n’est pas nécessaire de lier la «virtual property» à un objet ou!
! ! ! d’obtenir une valeur liée à cet objet. Lorsque vous définissez une «virtual property»!
! ! ! ou que vous utilisez sa valeur le «trigger» setProp ou l’appel getProp n’atteint pas le!
! ! ! moteur LiveCode mais est intercepté par un «handler».!
!
! ! ! setProp «handlers» pour une «virtual property»!
!
! ! ! Un «handler» setProp pour une «custom property» ordinaire inclut l’instruction de!
! ! ! contrôle pass permettant au «trigger» setProp d’atteindre le moteur LiveCode et de !
! ! ! définir la «custom property» (ou s’il inclut une commande set de définir!
! ! ! directement la «custom property»).!
! ! ! Un «handler» pour une «virtual property», en revanche, n’inclut pas d’instruction de!
! ! ! contrôle pass parce qu’une «virtual property» ne peut être définie (set). Étant!
! ! ! donné qu’une «virtual property» est automatiquement définie lorsque le «trigger»!
! ! ! atteint la fin du «message path», le «handler» qui lui est associé le «trigger» ne peut!
! ! ! transmettre l’instruction pass.!
!
! ! ! Si vous examinez les «custom properties» d’un objet après qu’une «virtual property»!
! ! ! ait été définie, vous remarquerez qu’aucune «custom property» n’aura été créée,!
! ! ! parce que le «handler» setProp intercepte l’appel ordonnant de définir la propriété.!
!
! ! ! getProp «handlers» pour une «virtual property»!
!
! ! ! De la même manière que précédemment, un «handler» getProp pour une «custom!
! ! ! property» ordinaire obtient directement la valeur de la propriété ou transmet!
! ! ! l’appel getProp de manière à ce que le moteur LiveCode puisse retourner cette!
! ! ! valeur. A contrario, dans le cas d’une «virtual property», l’objet ne contient pas la!
! ! ! propriété si bien que le «handler» getProp doit retourner la valeur recherchée.!
!
!
!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 23

! ! 11.06.04.!Créer les «virtual properties» d’un nouvel objet!

!
! ! ! Vous pouvez utiliser des «virtual properties» pour créer une nouvelle propriété qui!
! ! ! s’appliquera à tous les objets ou à tous les objets d’un type particulier. Une telle!
! ! ! propriété fonctionne de la même manière qu’une propriété intégrée car vous!
! ! ! pourrez l’utiliser avec n’importe quel objet, et, parce qu’une «virtual property» ne!
! ! ! repose pas sur le même principe qu’une «custom property», à savoir qu’elle ne doit!
! ! ! pas être reliée à un objet, vous n’êtes pas obligé de créer de propriété pour chaque!
! ! ! nouvel objet, la «virtual property» n’étant calculée que lorsque vous l’utilisez dans!
! ! ! une expression.!
!
! ! ! L’exemple suivant montre comment implémenter une «virtual property» nommée!
! ! ! cvPourcentageLargeur se comportant comme une propriété intégrée.!
!
! ! ! Définir la «virtual property» cvPourcentageLargeur!
!
! ! ! Supposons que vous placiez le «handler» cvPourcentageLargeur décrit!
! ! ! ci-avant dans le script de la pile (stack) au lieu du script du bouton :!
!
! ! ! setProp cvPourcentageLargeur vpNouveauPourcentage
set the width of the target to the width of the owner \
of the target * vpNouveauPourcentage div 100
end cvPourcentageLargeur
!
Les «triggers» setProp utilisant le «message path», si vous définissez the!
! ! ! cvPourcentageLargeur de n’importe quel objet dans votre pile (stack), la pile!
! ! ! (stack) recevra le «trigger» setProp (sauf s’il est intercepté auparavant par un autre!
! ! ! objet). Cela signifie que si le «handler» se trouve dans le script de la pile (stack) vous!
! ! ! pourrez définir the cvPourcentageLargeur de n’importe lequel des objets de!
! ! ! la pile (stack).!
!
! ! ! Si vous placez le «handler» dans un «backScript» vous pourrez définir the
cvPourcentageLargeur de n’importe quel des objets placé n’importe où dans!
! ! ! l’application.!
!
! ! ! Obtenir la valeur de la «virtual property» cvPourcentageLargeur!
!
! ! ! Le getProp «handler» vous permettant de récupérer la valeur de the
cvPourcentageLargeur d’un objet ressemble à cela :!
!
! ! ! getProp cvPourcentageLargeur
return 100 * (the width of the target div the width \
of the owner of the target)
end cvPourcentageLargeur
!
Si vous placez le «handler» ci-dessus dans le script d’un bouton de carte, le code!
! ! ! suivant retournera la largeur du bouton sous forme de pourcentage :!
!
! ! ! put the cvPourcentageLargeur of btn “btnBouton“ into fld 12
!
Si, par exemple, la pile (stack) à une largeur de 320 pixels et le bouton une largeur de!
! ! ! 50 pixels, la largeur (width) du bouton représente les 15% de la largeur de la pile!
! ! ! (stack), le résultat du code ci-dessus retournera la valeur 15 dans le champ (fld) 12.!
!
! ! ! Comme le «handler» setProp, le «handler» getProp doit être placé loin dans le «message!
 LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 AOÛT 2013 PAGE 24

! ! ! path». Le fait de le placer dans le script de pile (stack) permet de le rendre opérant!
! ! ! pour tous les objets de la pile (stack). Le placer dans un «backScript» permet de le!
! ! ! rendre opérant pour tous les objets de l’application, si celle-ci est composée de!
! ! ! plusieurs piles (stacks).!
!
! ! ! Limiter la «virtual property» cvPourcentageLargeur!
!
! ! ! La plupart des propriétés intégrées ne s’appliquent pas à tous les types d’objets.
! ! ! Vous pouvez, de la même manière, créer une «virtual property» qui ne concernera!
! ! ! qu’un certain type d’objets. Il n’est pas très utile, par exemple, de connaître la!
! ! ! largeur d’un «substack» ou la largeur d’une carte sous la forme du pourcentage de la!
! ! ! largeur de la pile principale (main stack).!
!
! ! ! Vous pouvez limiter la définition de cette propriété à certains objets en vérifiant le!
! ! ! nom de l’objet cible :!
!
! ! ! setProp cvPourcentageLargeur vpNouveauPourcentage
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 * vpNouveauPourcentage div 100
end cvPourcentageLargeur!
!
! ! ! Nota : pour faire référence à l’objet dont la propriété est définie, utilisez la fonction !
! ! ! target. Target fait référence à l’objet qui a reçu le «trigger» setProp même si le!
! ! ! «handler» en cours d’exécution est placé dans le script d’un autre objet.!
!
! ! ! Le premier mot du nom d’un objet (word 1 of the name) est le type de l’objet, !
! ! ! l’exemple ci-dessus montre comment ignorer la modification de largeur si les objets!
! ! ! sont des cartes (card) ou des piles (stack).