[Rezilla-commits] RezillaExtras/Aida/Docs_Input PluginSupport_EN.aida, 1.6, 1.7 PluginSupport_FR.aida, 1.4, 1.5

[Bernard D. <bde...@us...>]

Update of /cvsroot/rezilla/RezillaExtras/Aida/Docs_Input
In directory sc8-pr-cvs9.sourceforge.net:/tmp/cvs-serv4106

Modified Files:
	PluginSupport_EN.aida PluginSupport_FR.aida 
Log Message:
Doc complements

Index: PluginSupport_EN.aida
===================================================================
RCS file: /cvsroot/rezilla/RezillaExtras/Aida/Docs_Input/PluginSupport_EN.aida,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- PluginSupport_EN.aida	1 Nov 2006 17:00:52 -0000	1.6
+++ PluginSupport_EN.aida	24 Nov 2006 08:56:16 -0000	1.7
@@ -409,26 +409,47 @@
 private data which Rezilla will pass back in all its calls to interface 
 functions.
 
-((li after Rezilla receives acceptance and requests from the plugin, it 
-invokes the ((i EditResource i)) function. Through this function the 
-plugin receives a ((i RezHostInfo i)) structure filled by Rezilla and 
-containing basic information such as a ((i WindowRef i)) for the editing window, 
-the ((i MenuRef i)) pointers in case the plugin needs some menus, etc.
+((li after Rezilla receives acceptance and requests from the plugin, it
+invokes the ((i EditResource i)) function. Through this function the plugin
+receives a ((i RezHostInfo i)) structure filled by Rezilla and containing
+basic information such as a ((i WindowRef i)) for the editing window, the
+((i MenuRef i)) pointers in case the plugin needs some menus, etc.
 lo))
 
-At this point the plugin can do its job to edit the resource. It can 
-populate the window with controls and graphic elements, install CarbonEvents on these controls, 
-etc. Note though that the plugin is not obliged to use CarbonEvents; the basic user actions 
-are passed to it by Rezilla with an EventRecord via the following 
-functions declared in the interface: 
+At this point the plugin can do its job to edit the resource. It can
+populate the window with controls and graphic elements, install
+CarbonEvents on these controls if necessary, etc. The window provided by
+Rezilla is constructed in compositing mode: this makes the HIView drawing
+model fully available.
+
+Note though that the plugin is not obliged to use CarbonEvents; the basic
+user actions are passed to it by Rezilla with an EventRecord via the
+following functions declared in the interface:
 ((i HandleMenu, HandleClick, HandleKeyDown i)) and ((i HandleCommand i)).
 
 When it is time to save the modifications made in a resource (for instance
-when the user clicks on the ((i Save i)) button or attempts to close the window),
-Rezilla invokes the ((i ReturnResource i)) function so that the plugin
-returns the new data and then the ((i CleanUp i)) function so that it can
-perform any post editing tasks, like releasing allocated memory for
-instance.
+when the user clicks on the ((i Save i)) button or attempts to close the
+window), Rezilla invokes the ((i ReturnResource i)) function so that the
+plugin returns the new data and then the ((i CleanUp i)) function so that
+it terminates its editing session.
+((lu
+((li the ((i ReturnResource i)) function returns a handle to the data. It
+also has a boolean argument named ((i releaseIt i)) to tell Rezilla who is
+the owner of this handle and should dispose of it. If ((i releaseIt i)) is
+set to true, Rezilla will dispose of the handle after the resource is
+saved. Otherwise the plugin assumes ownership.
+
+((li when the ((i CleanUp i)) function is called, the plugin should perform
+any post editing tasks, release allocated memory, etc.
+
+lu))
+
+If the user clicks on the ((i Revert i)) button (if there is one!), Rezilla
+invokes the ((i RevertResource i)) function: the data to revert to are
+provided in the ((i inDataH i)) argument, so the plugin does not have to
+worry about keeping a copy of the original data.
+
+
 
 ((s3 Plugin requests
 
@@ -449,10 +470,13 @@
 |))
 
 The ((i winbounds i)) member is a Rect structure indicating the position
-and dimension of the editing window. Rezilla always provides an editing
-window which can be equiped with some basic controls such as a ((i Save i)) button,
-a ((i Cancel i)) button etc. The plugin does not have to track these controls: they
-are managed by the main application. The plugin just decides, using the
+and dimension of the editing window: it is in global coordinates and
+corresponds to the entire structure of the window, that is to say the
+dimensions that will be passed to the ((i CreateWindow i)) toolbox
+function. Rezilla always provides an editing window which can be equiped
+with some basic controls such as a ((i Save i)) button, a ((i Cancel i))
+button etc. The plugin does not have to track these controls: they are
+managed by the main application. The plugin just decides, using the
 appropriate flags, which controls should be present in the editing window.
 For instance, add the ((i kPluginEditorHasRevertButton i)) flag to the
 attributes to get a ((i Revert i)) button.

Index: PluginSupport_FR.aida
===================================================================
RCS file: /cvsroot/rezilla/RezillaExtras/Aida/Docs_Input/PluginSupport_FR.aida,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- PluginSupport_FR.aida	1 Nov 2006 17:00:53 -0000	1.4
+++ PluginSupport_FR.aida	24 Nov 2006 08:56:16 -0000	1.5
@@ -464,22 +464,44 @@
 lo))
 
 Ë ce stade, le plugin peut maintenant faire son travail d'Ždition de la
-ressource. Il peut par exemple crŽer des contr™les et des ŽlŽments 
-graphiques, installer des
-CarbonEvents sur ces contr™les, etc. On notera dependant qu'il n'y a aucune
-obligation ˆ utiliser des CarbonEvents; toutes les actions et ŽvŽnements
-dŽclenchŽs par l'utilisateur sont passŽs ˆ Rezilla sous la forme d'un
-EventRecord dans les fonctions suivantes dŽfinies dans l'interface:
-((i HandleMenu, HandleClick, HandleKeyDown i)) et ((i HandleCommand i)).
+ressource. Il peut par exemple crŽer des contr™les et des ŽlŽments
+graphiques, installer au besoin des CarbonEvents sur ces contr™les, etc. La
+fentre est construite en mode composite (((i compositing mode i))) ce qui
+permet d'utiliser pleinement le modle HIViews de dessin de l'interface 
+graphique.
+
+On notera dependant qu'il n'y a aucune obligation ˆ utiliser des
+CarbonEvents; toutes les actions et ŽvŽnements dŽclenchŽs par l'utilisateur
+sont passŽs ˆ Rezilla sous la forme d'un EventRecord dans les fonctions
+suivantes dŽfinies dans l'interface: ((i HandleMenu, HandleClick,
+HandleKeyDown i)) et ((i HandleCommand i)).
 
 Lorsque vient le moment de sauvegarder les modifications faites dans la ressource
  (par exemple lorsque l'utilisateur clique sur le bouton ((i Save i)) 
 ou tente de fermer la fentre), 
 Rezilla invoque la fonction ((i ReturnResource i)) afin que le plugin 
 renvoie les donnŽes modifiŽes, puis la fonction ((i CleanUp i)) 
-afin qu'il puisse exŽcuter les t‰ches qui mettent fin ˆ une session 
-d'Ždition, comme par exemple libŽrer les portions de mŽmoire qui ont ŽtŽ 
-allouŽes.
+afin qu'il puisse terminer sa session d'Ždition:
+((lu
+((li la fonction ((i ReturnResource i)) renvoie une ((i handle i)) sur les
+donnŽes modifiŽes. Elle comporte aussi un argument boolŽen ((i releaseIt
+i)) qui indique ˆ Rezilla qui est propriŽtaire de cette ((i handle i)) et
+qui devra donc libŽrer la mŽmoire qu'elle occupe. Si cet argument est fixŽ
+ˆ la valeur ((i true i)) c'est Rezilla qui est responsable de libŽrer la
+mŽmoire, autrement le plugin devra s'en charger.
+
+((li lorsque la fonction ((i CleanUp i)) est appelŽe, le plugin exŽcute 
+toutes les t‰ches de post-Ždition qu'il juge nŽcessaire, libre la mŽmoire 
+qu'il a allouŽe, etc.
+
+lu))
+
+Si l'utilisateur clique sur le bouton ((i Revert i)) (lorsqu'il y en a
+un!), Rezilla invoque la fonction ((i RevertResource i)): les donnŽes
+auxquelles il faut revenir sont fournies par l'intermŽdiaire de l'argument
+((i inDataH i)), ce qui signifie en particulier que le plugin n'a pas ˆ se
+prŽoccuper de garder une copie des donnŽes originales.
+
 
 ((s3 Les requtes du plugin
 
@@ -502,14 +524,17 @@
 |))
 
 Le membre ((i winbounds i)) est une structure Rect indiquant la position et
-dimension de la fentre d'Ždition. Rezilla fournit toujours une fentre
-d'Ždition qui peut tre ŽquipŽe d'un certain nombre d'ŽlŽments de base tels
-que des boutons ((i Save i)) et ((i Cancel i)). Le plugin n'a pas ˆ se
-prŽoccuper de surveiller ces contr™les: ils sont gŽrŽs par l'application
-principale. Le plugin doit simplement dŽcider, au moyen des drapeaux
-adŽquats, lesquels de ces contr™les doivent figurer dans la fentre. Par
-exemple, on ajoutera le drapeau ((i kPluginEditorHasRevertButton i)) aux
-attributs si l'on souhaite avoir un bouton ((i Revert i)) dans la fentre.
+dimension de la fentre d'Ždition: elle est exprimŽe en coordonnŽes
+globales et correspond ˆ la structure entire de la fentre, autrement les
+dimensions qui sont habituellement passŽes ˆ la fonction ((i CreateWindow
+i)). Rezilla fournit toujours une fentre d'Ždition qui peut tre ŽquipŽe
+d'un certain nombre d'ŽlŽments de base tels que des boutons ((i Save i)) et
+((i Cancel i)). Le plugin n'a pas ˆ se prŽoccuper de surveiller ces
+contr™les: ils sont gŽrŽs par l'application principale. Le plugin doit
+simplement dŽcider, au moyen des drapeaux adŽquats, lesquels de ces
+contr™les doivent figurer dans la fentre. Par exemple, on ajoutera le
+drapeau ((i kPluginEditorHasRevertButton i)) aux attributs si l'on souhaite
+avoir un bouton ((i Revert i)) dans la fentre.
 
 Le membre ((i menucount i)) indique combien de menus sont nŽcessaires au
 plugin (Žventuellement 0). Si le plugin dŽfinit des menus, il doit passer