path: root/doc/manuel_utilisateur.txt

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