Documentation de la bibliothèque libText 2.0

Présentation de libText

Origine de la bibliothèque

La bibliothèque libText a été crée pour pouvoir moduler facilement les polices d'écriture car celles du système ne sont pas très "performantes". La petite n'offre pas de clipping et les deux manquent de caractères spéciaux. Le but de la libText est de permettre facilement l'implémentation de polices pour améliorer le style d'écritures des programmes et permettre des polices plus spécifiques, souvent moins coûteuses en mémoire que des images.

Avantages et inconvénients

Puisque la libText offre plus de liberté, en particulier au niveau du clipping, elle est forcément plus lente. Néanmoins, elle reste suffisament rapide pour faire défiler du texte et la différence avec les polices du système ne se sent pas dans le cas d'interfaces fixes. De plus, elle permet d'écrire de trois manières :

En noir sur blanc ;
En blanc sur noir ;
En inversant les pixels.

Les deux premiers style peuvent être appliqués avec ou sans transparence, ce qui fait 5 styles d'écriture.
Surtout, elle permet le clipping dans tous les cas, ce qui est nécessaire à toute animation fluide.

Utilisation de libText

Pour utiliser libText dans un programme, il vous suffit, après avoir extrait le fichier source (LibText.c) et l'en-tête (LibText.h) dans le dossier des données de votre projet, d'ajouter le premier au projet (dans la fenêtre Files in project du SDK) et d'inclure le second à l'aide de la directive #include au début de chaque fichier source de votre projet qui fait appel à une fonction de la bibliothèque.

Remerciements

Merci à Dark Storm pour avoir spontanément partagé sa police Arcadium.

Liste des fonctions

Fonctions fondamentales

void Txt_Init(int fonts);// Prototype
Txt_Init(FONT_MINISD | FONT_SYSTEM);// Exemple

DESCRIPTION	Initialise les polices à partir du paramètres fonts.
RETOUR	Ne retourne rien.
DEPENDANCES	`malloc()`
VOIR AUSSI	Le paramètre d'initalisation

void Txt_Quit(void);// Prototype
Txt_Quit();// Exemple

DESCRIPTION	Libère les polices à la fin de l'exécution.
RETOUR	Ne retourne rien.
DEPENDANCES	`free()`

Fonctions de texte

void Txt_Text(const char *s, int x, int y, int f, int m);// Prototype
Txt_Text(~~"libText example"~~,10,20,TXT_SYSTEM,TXT_REV);// Exemple

DESCRIPTION	Écrit la chaîne de caractères s aux coordonnées (x;y) en en utilisant la police f dans le mode m.
RETOUR	Ne retourne rien.
DEPENDANCES	`Txt_Char()`, `Txt_Point()`
VOIR AUSSI	Les polices Les modes de texte

void Txt_Char(char c, int x, int y, int f, int w, int h, int m);// Prototype
Txt_Char(~~'A'~~,10,30,Txt_Fonts[0],3,5,TXT_XOR);// Exemple

DESCRIPTION	Cette fonction n'est pas destinée à être utilisée directement. Elle affiche un caractère.
RETOUR	Ne retourne rien.
DEPENDANCES	`Txt_Point()`
VOIR AUSSI	Les polices Les modes de texte

Fonctions internes

void Txt_Point(int x, int y, int v, int m);// Prototype
Txt_Point(4,52,1,TXT_AND);// Exemple

DESCRIPTION	Fonction étendue d'affichage de pixel. Prend en compte le mode logique.
RETOUR	Ne retourne rien.
DEPENDANCES	`Txt_Pixel()`

void Txt_Pixel(int x, int y, int v);// Prototype
Txt_Pixel(5,12,0);// Exemple

DESCRIPTION	Affiche le pixel aux coordonnées (x;y) à la couleur v.
RETOUR	Ne retourne rien.

int Txt_Get(int x, int y);// Prototype
int color = Txt_Get(29,35);// Exemple

DESCRIPTION	Renvoie la couleur du pixel aux coordonnées (x;y), sans vérification de celles-ci.
RETOUR	Retourne la couleur du pixel.

Les polices

MiniSD

PROPRIÉTÉS

3

5

Taille du
caractère

Nom pour l'initialisation	`FONT_MINISD`
Nom pour l'écriture	`TXT_MINISD`
Développée par	LePhenixNoir

System

PROPRIÉTÉS

5

7

Taille du
caractère

Nom pour l'initialisation	`FONT_SYSTEM`
Nom pour l'écriture	`TXT_SYSTEM`
Développée par	CASIO

Arcadium

PROPRIÉTÉS

5

Taille du
caractère

Nom pour l'initialisation	`FONT_ARCADIUM`
Nom pour l'écriture	`TXT_ARCADIUM`
Développée par	Dark Storm

Documentation des polices

Le paramètre d'initialisation

Le paramètre d'initialisation a sa propre syntaxe. Il suffit de mettre le nom des polices à initialiser et de les séparer du caractère '|'. Vous pouvez bien entendu ajouter tous les espaces que voulez. Par exemple :

Txt_Init(FONT_MINISD | FONT_ARCADIUM);

POLICE	TAILLE	CODE À UTILISER
MiniSD	3 * 5	FONT_MINISD
System	5 * 7	FONT_SYSTEM
Arcadium	5 * 5	FONT_ARCADIUM

Les modes de texte

La libText permet d'écrire le texte selon 5 modes.

MODE	DESCRIPTION	IMAGE
TXT_OR	Police noire, fond transparent
TXT_ON	Police noire, fond blanc
TXT_AND	Police blanche, fond transparent
TXT_REV	Police blanche, fond noir
TXT_XOR	Police inversante, fond transparent

Tutoriel d'utilisation

Présentation

Ce tutoriel est fait pour vous aider à prendre en main la bibliothèque, car il n'est pas toujours simple de coder n'ayant que la documentation. Avant toute chose, vous devez extraire les fichiers LibText.c et LibText.h dans le dossier de votre projet. Ensuite, utilisez la directive #include pour inclure le header dans chaque fichier source qui utilise une fonction de la lib.

#include

~~"LibText.h"~~

Initialisation

Pour utiliser la bilbiothèque, vous devez appeler la fonction d'initialisation au début de votre programme. Il est conseillé de le faire au début de la fonction AddIn_main(). La fonction d'initialisation ne prend qu'un seul paramètre. Il s'agit d'une valeur qui permet de lui indiquer quelles polices le programme utilisera. Vous devez systématiquement initialiser toutes les polices que vous allez utiliser dans le projet, et non seulement celles que vous utiliserez dans le fichier source qui appelle Txt_Init().
Exemple d'appel à Txt_Init() :

Txt_Init(FONT_SYSTEM | FONT_ARCADIUM);

Le paramètre d'initialisation

Afficher du texte

Afficher du texte est très simple, il n'y a qu'une seule fonction, Txt_Text(). Son protoype est le suivant :

void Txt_Text(const char *s, int x, int y, int f, int m);

Le paramètre s est le texte à afficher. Viennent ensuite x et y les coordonnées de l'écran où le texte doit être affiché. Les deux derniers paramètres sont respectivement la police dans laquelle le texte doit être écrit et le mode d'écriture.
Exemple d'affiche de texte :

Txt_Text(~~"Exemple de texte"~~,20,37,TXT_ARCADIUM,TXT_OR);

Les polices
Les modes de texte

Quitter le programme

Lorsque vous avez initialisé la bibliothèque avec Txt_init(), celle-ci a alloué de la place en mémoire pour stocker des données. À la fin de l'exécution, il est important de libérer cet espace mémoire pour d'autres applications. Appelez donc, juste à la fin de votre AddIn_main() (mais avant le return, attention), la fonction Txt_Quit(). Elle se charge de tout et ne prend aucun paramètre.

Txt_Quit();