Le manuel est écrit en français. Laissons le nom libre pour une future version en anglais.

1 files changed, 372 insertions, 0 deletions

diff --git a/doc/manuel_utilisateur.txt b/doc/manuel_utilisateur.txt
new file mode 100644
index 0000000..3bbcdb2
--- /dev/null
+++ b/doc/manuel_utilisateur.txt
@@ -0,0 +1,372 @@
+Ce manuel utilisateur a pour objectif de faciliter l'utilisation de MTools.
+
+La première patie décrit en détail les fonctionnalités générales c'est à dire
+celles communes à tous les objets MTools.
+
+La deuxième partie décrit l'utilisation spécifique de chaque objet.
+
+
+PARTIE 1 : Les fonctionnalités communes
+---------------------------------------
+
+1.1 MTools.pm
+-------------
+
+Cette partie de la documentation est principalement extraite de MTools.pm
+
+MTools exporte des fonctions destinées principalement à :
+	- activer des fonctions propres à la librairie mtools
+	- assurer la compatibilité entre la manipulation des objets mtools et
+	des objets zinc
+
+Ainsi, d'une manière générale, toutes fonctions exportées s'appliquent aussi
+bien à des objets zinc qu'à des objets mtools. L'unique restriction est dans la
+méthode d'appel :
+	- obligatoirement : fct ($obj, @parametres) pour un objet zinc
+	- indiferemment $obj -> fct (@parametres).
+L'avantage de la première méthode est qu'elle s'applique aussi bien à un objet
+zinc qu'à un objet MTools. L'inconvénient est que l'on perd la possibilité de
+profiter de l'héritage et de la redéfinition éventuelle de la fonction.
+
+La fonction particuliere "new" :
+	La fonction "new" permet de générer une nouvelle frame encapsulant un
+	canvas zinc.
+	Une frame MTools est unique pour une application.
+	Elle initialise par ailleurs les données génériques pour le
+	fonctionnement de MTools.
+
+Les callbacks dans MTools :
+	\&fct : exécution de fct ()
+	[\&fct, @params] : exécution de fct (@params)
+	['fct_name', $obj, @params] : exécution de $obj -> fct_name (@params)
+	[$obj, 'fct_name', @params] : exécution de $obj -> fct_name (@params)
+	[$obj, \&fct_name, @params] : exécution de fct_name ($obj, @params)
+
+Fonctions :
+	- propertyExists : teste si une propriété MTools a été enregistrée (par
+	recordProperty) pour l'objet en question. S'il s'agit d'un objet zinc la
+	valeur retournée est forcément 0.
+	- mconfigure : permet de configurer indifférement des propriétes zinc ou
+	MTools d'un objet. Les paramètres sont passés sous forme d'une table de
+	hash. Par habitude, les propriétes zinc ou definies pour assurer une
+	compatibilité avec zinc (comme '-visible') ont été précédées d'un '-'.
+	- mget : $obj -> mget ('propriete') permet de récupérer la valeur d'une
+	propriété
+	- plisten : $obj -> plisten ('property_name', callback) plisten permet
+	d'écouter les modifications des propriétés mtools d'un objet => associe
+	l'appel d'une fonction à la modification d'un objet MTools
+	- unplisten : $obj -> unplisten ('property_name', callback) supprime
+	l'écoute
+	- plink : plink ([$obj1, 'property_1'], [$obj2, 'property_2'], ...);
+	Synchronise n propriétés. Si property_1 est modifiée, property_2 prendra
+	la valeur de property_1 et réciproquement. À l'initialisation, toutes
+	les propriétés prennent la valeur de property_1.
+	- executer : executer (callback); permet d'exécuter une callback du type
+	predefini ci-dessus dans la section "Les callbacks dans MTools"
+	- binding : $obj -> binding ('evenement', callback) permet d'écouter un
+	évènement MTOOLS ou Tk survenant sur un objet. binding peut aussi être
+	redéfini pour écouter de nouvelles sources d'évènements (par exemple
+	MIvy ou WacomAdapter)
+	- unbinding : $obj -> unbinding ('evenement', callback) arrête l'écoute
+	d'un évènement
+	- minstanciate : minstanciate ('definition', $parent) permet de
+	retourner un objet MTools à partir de la spec 'definition'
+	. si 'definition' est un path svg, minstanciate instancie le svg et
+	  retourne un objet MTools encapsulant le contenu
+	. si 'definition' est un objet zinc, minstanciate retourne un objet
+	  MTools encapsulant l'objet zinc
+	. si 'definition' est déjà un objet MTools, minstanciate retourne
+	  l'objet lui-meme.
+	minstanciate change également le groupe parent qui deviendra
+	obligatoirement $parent
+	- minstance : minstance ($objet, $parent) est le cousin de minstanciate
+	mais lui retourne obligatoirement un objet zinc
+	- mrun : lance l'exécution de la main loop.
+	- mfind : $objet -> mfind ('tag') permet de chercher un fils de l'objet
+	ayant le tag correspondant
+	- mplaying : permet de lire un fichier son
+
+Les fonctions suivantes encapsulent l'exécution des fonctions zinc
+associées. Voir la documentation zinc :
+http://www.tkzinc.org/Documentation/refman-3.3.4/index.html
+	- raise
+	- scale
+	- translate
+	- rotate
+	- coords
+	- bbox
+	- type
+	- tset
+	- treset
+	- tget
+	- clone
+	- chggroup
+	
+1.2 MObjet.pm
+-------------
+
+Cette partie de la documentation est principalement extraite de MObjet.pm
+
+Le composant MObjet est l'objet racine des composants MTools.
+Il definit les fonctions applicables uniquement aux objets MTools.
+
+IMPORTANT : Une autre partie des fonctions applicables aux objets MTools est
+définie dans la classe MTools. La différence entre ces deux classes de fonctions
+est que les fonctions définies dans MTools sont également applicables à des
+objets zinc tandis que les fonctions définies ici ne peuvent être appliquées
+qu'à des objets héritant de MTools::MObjet.
+
+Concepts :
+	- Objet MTools : objet héritant de MObjet
+	- Les PROPERTY : les propriétés sont des attributs particuliers et
+	modifiables par un appel à "mconfigure". Elles peuvent être écoutées et
+	synchronisées avec d'autres propriétés MTools ou meme zinc ! (cf
+	MTools::plink et MTools::plisten). En conséquence elles sont là pour
+	engendrer un comportement consécutif à leur modification et doivent être
+	distinguées des attibuts qui peuvent se contenter d'être des clef de
+	hash de l'objet.
+	- Les EVENT : les évènements peuvent être émis par n'importe quel objet
+	MTools et captés par un binding.
+
+Les fonctions publiques :
+	- recordEvent : permet de permettre à un objet MObjet d'émettre un
+	évènement.
+	- recordProperty : permet de déclarer et initialiser une propriété.
+	NOTA : il pourrait manquer une déclaration collective des
+	propriétés. Initialement, celle-ci n'a pas été effectuée pour essayer de
+	limiter l'usage des propriétés et ne pas les utiliser comme des
+	attributs.
+	- notify : permet à un objet MTools de notifier un évènement
+	préalablement enregistré par recordEvent
+	- propagate : permet à un objet de propager un évènement émis par un
+	autre objet (correspond à un recordEvent puis un binding sur un
+	évènement d'un objet effectuant le notify du meme évènement depuis
+	l'objet declarant la propagation)
+
+
+PARTIE 2 : Les objets de MTools
+-------------------------------
+
+2.1 Les éléments graphiques
+---------------------------
+
+Les objets graphiques élémentaires sont de type MObjet. Ils se trouvent dans
+MTools::GUI.
+_______
+MCircle : l'objet cercle. La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- x, y : coordonnées du centre du cercle
+	- r : rayon du cercle
+	- %options : table de hash passée en paramètre de la création de l'objet
+	zinc arc
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MCircle;
+new MTools (800, 600, "Exemple de cercle");
+my $cercle = new MTools::GUI::MCircle (1, 400, 300, 200);
+my $disque = new MTools::GUI::MCircle (1, 400, 300, 200,
+				       -filled => 1, -fillcolor => red);
+mrun;
+________
+MRect.pm :  l'objet rectangle. La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- x, y : coordonnées de l'angle en haut à gauche du rectangle
+	- w, h : largeur et hauteur du rectangle
+	- %options : table de hash passée en paramètre de la création de l'objet
+	zinc rectangle
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MRect;
+new MTools (800, 600, "Exemple de rectangle");
+my $contour = new MTools::GUI::MRect (1, 400, 300, 200, 10);
+my $surface = new MTools::GUI::MRect (1, 400, 400, 200, 20,
+				     -filled => 1, -fillcolor => red);
+mrun;
+_________
+MGroup.pm : cet objet permet de regrouper d'autres objets, qui peuvent aussi
+être des groupes. Le groupe est vu et manipulé comme un objet unique.
+La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- %options : table de hash passée en paramètre de la création de l'objet
+	zinc groupe
+
+Exemple d'utilisation :
+use Math::Trig;
+use MTools;
+use MTools::GUI::MRect;
+use MTools::GUI::MGroup;
+new MTools (800, 600, "Exemple de groupe");
+my $group = new MTools::GUI::MGroup (1);
+my $contour = new MTools::GUI::MRect ($group, 400, 300, 200, 10);
+my $surface = new MTools::GUI::MRect ($group, 400, 400, 200, 20,
+				     -filled => 1, -fillcolor => red);
+clone($group);
+$group->rotate(pi/4, 400, 300);
+mrun;
+________
+MClip.pm : l'objet permettant de faire du clipping. Le clipping est une
+technique qui consiste à réaliser une fenêtre de visualisation. En pratique,
+le clip est un objet qui définit une surface. Les portions du groupe clippé qui
+se trouvent à l'intérieur de cette surface sont visibles, tout ce qui est en
+dehors n'est pas affiché.
+La création nécessite les arguments suivants :
+	- clipped : groupe zinc clippé
+	- path : description de l'objet clippant
+		- soit une descrition sous forme [_type, _coords] créant un
+		objet zinc de type _type et de coordonnées _coords
+		- soit un objet existant qui prendra pour père le groupe
+		$clipped.
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MGroup;
+use MTools::GUI::MCircle;
+use MTools::GUI::MRect;
+use MTools::GUI::MClip;
+new MTools (800, 600, "Exemple de clip");
+my $fenetre = new MTools::GUI::MGroup (1);
+my $disque = new MTools::GUI::MCircle ($fenetre, 400, 300, 100, -filled => 1);
+my $trou = new MTools::GUI::MRect ($fenetre, 250, 300, 100, 60);
+new MTools::GUI::MClip ($fenetre, $trou);
+mrun;
+_________
+MCurve.pm : l'objet curve permet de réaliser une forme quelconque, composée de
+segments et de courbes de Bézier.
+La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- coords : coordonnées de la curve (cf. format zinc)
+	- %options : table de hash passée en paramètre de la création de l'objet
+	zinc curve
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MCurve;
+new MTools (800, 600, "Exemple de curve bémol");
+my $b = new MTools::GUI::MCurve(1, [[100, 100], [100, 300], # barre verticale
+				    [200, 300, 'c'], # bas de l'arrondi
+				    [200, 200, 'c'], # haut de l'arrondi
+				    [100, 250]],-linewidth=>3);#point d'accroche
+mrun;
+_________
+MImage.pm : l'objet image permet de charger une image à partir d'un fichier.
+Actuellement, MImage gère les images au format png. Les autres formats marchent
+probablement, à vérifier*** (à moins que ce soit pour les svg).
+La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- image : nom de l'image
+	- %options : table de hash passée en paramètre de la création de l'objet
+	zinc icon
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MImage;
+new MTools (800, 600, "Exemple d'image");
+my $image = new MTools::GUI::MImage (1, "plan.png");
+mrun;
+________
+MText.pm : l'objet texte permet d'afficher des caractères.
+La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- text : le texte à afficher
+	- x, y : coordonnées de l'emplacement de l'objet
+	- %options : table de hash passée en paramètre de la création de l'objet
+	zinc text
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MText;
+new MTools (800, 600, "Exemple de texte");
+my $message = new MTools::GUI::MText(1,"Texte d'exemple",100,100,-color=>gray);
+mrun;
+___________
+MTexture.pm :
+Permet d'appliquer une texture à un objet. Une texture est une image qui sert de
+motif au remplissage d'une figure. Comme pour une tapisserie, la texture est
+répétée autant de fois que nécessaire pour couvrir toute la surface. Le coin en
+haut à gauche de la texture est aligné avec le coin en haut à gauche de la bbox
+de la figure à remplir.
+La création nécessite les arguments suivants :
+	- parent : père de l'objet.
+	- target : groupe zinc ou objet MTools définissant le contour de la
+	figure.
+	- image_name : nom de l'image texture (fichier png) Tester avec les
+	autres formats***
+
+Exemple d'utilisation :
+use MTools;
+use MTools::GUI::MCurve;
+use MTools::GUI::MTexture;
+new MTools (800, 600, "Exemple de texture");
+my $surface = new MTools::GUI::MCurve (1, [[150, 50],
+					   [400, 100, 'c'],
+					   [750, 50],
+					   [750, 550],
+					   [400, 500, 'c'],
+					   [50, 550]]);
+my $texture = new MTools::GUI::MTexture(1, $surface, "plan.png");
+mrun;
+
+2.2 Le SVG
+----------
+SVG signifie Scalable Vector Graphics. Il s'agit d'un format standard puisqu'il
+correspond à une spécification du W3C. Cette standardisation permet aux fichiers
+svg d'être utilisés par plusieurs applications (par exemple Adobe Illustrator,
+inkscape sous Linux). Les fichiers svg permettent de décrire une image de
+manière vectorielle (par opposition à la description matricielle d'une
+photo). Les fichiers svg vont être utilisés pour décrire l'apparence des
+éléments graphiques d'une interface. Le graphiste pourra alors faire évoluer
+l'aspect d'une interface en modifiant les fichiers svg avec son éditeur
+favori. Cela revient à externaliser l'aspect visuel du code qui gère les
+comportements.
+NOTE : pour que la collaboration entre développeur et designer graphique se
+passe bien, il est important de définir clairement l'interface d'échange.
+
+Un outil de conversion (SVG2zinc) lit un fichier svg et le convertit en code
+perl. Ce code perl crée les objets graphiques zinc équivalents à ceux décrits
+dans le svg. Le code perl est généré dans le répertoire AUTOGEN. Le code perl
+est automatiquement regénéré si le fichier svg a été modifié.
+
+Le code perl construit des objets zinc, on a donc un arbre d'objets zinc qui
+reflète la description du svg.
+
+Il existe plusieurs manières de créer des objets graphiques à partir de la
+description contenue dans un fichier svg :
+- SVGLoader::load(svg, groupe parent)
+	Cette fonction actualise AUTOGEN si nécessaire.
+	Elle crée et retourne un objet perl dont le nom du type est construit à
+	partir du nom svg. Cet objet hérite de MGroup. Le groupe parent est
+	celui donné en paramètre.
+- MTools::minstanciate(svg, groupe parent)
+	Cette fonction fait appel à SVGLoader::load et retourne un objet MTools.
+	L'avantage de cette fonction c'est qu'elle est facile d'accès à tous les
+	objets qui héritent de MTools.
+	NOTE : cette fonction sait faire plus que charger du svg, voir le
+	chapitre traitant de MTools.pm pour plus de détails.
+- MTools::minstance : minstance (svg, groupe parent)
+	Idem que minstanciate mais retourne obligatoirement un objet zinc.
+- MSwitch : la description des états d'un switch peut utiliser directement un
+	nom svg. Voir la description de MSwitch.
+
+2.3 Les widgets
+---------------
+
+2.4 Les transformations
+-----------------------
+
+2.5 Les animations
+------------------
+
+2.6 Les comportements
+---------------------
+
+________________________
+MAntiRecouvrementItem.pm :
+
+
+2.7 Les inclassables
+
+ptkdb, MObjet, MTimer, MState, MSwitch, MIvy, WacomAdapter
+
+2.8 L'utilisation de TkZinc