LIVECODE > DOCUMENTATION FRANÇAISE VERSION 1.0 DU 15 … · 2014-01-08 · LIVECODE >...

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).