diff options
Diffstat (limited to 'doc/manuel_utilisateur.txt')
| -rw-r--r-- | doc/manuel_utilisateur.txt | 372 |
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 |