Intro

Il namespace TAGS contiene le classi base per la definizione di tags e liste di tags: TAG e TAG_list.

Il file TIFF (acronimo di Tagged Image File Format) permette l’accesso alle diverse informazioni salvate attraverso l’indicazione del tag,  un valore numerico che le identifica;

Le classi contenute nel namespace TAGS svolgono un compito analogo,  permettendo la ricerca in un indice di tag (TAG_list) di informazioni di qualunque genere; La differenza sostanziale è che gli indici sono in forma alfanumerica e che le informazioni corrispondono a classi e strutture C++ memorizzbili su file; Di seguito presenteremo in dettaglio le classi TAG e TAG_list e le specifiche di costruzione delle classi di tipo TAG;

Avvertenza: in questo articolo è definito tag una qualunque istanza di una classe derivata da TAG, cioè che possiede l’interfaccia TAG.  definiremo tag_list una qualunque istanza di una classe TAG_list.

TAG

Un TAG è una classe contenitore di dati; tutte le classi derivate da TAG sono dotate di un identificatore (definibile attraverso la funzione Set_id) che è specifico delle stesse; ad esempio tutte le istanze di classe DocumentSize hanno lo stesso identificatore.

Ciascuna istanza di una classe derivata da TAG è dotata di nome, definito attraverso la funzione Set_name; Il nome dell’istanza è utilizzato per ricercare la stessa in una lista di TAG: per default, in assenza di definizione del nome, il nome è posto uguale all’identificatore della classe, ma in una lista è inseribile un solo tag per ciascun nome; quindi se si inseriscono più tag in una tag_list, ciascun avrà un nome unico, indipendentemente dal tipo.

class AFX_EXT_CLASS TAG
{
   friend class TAG_list;
   public:
	TAG();
	~TAG();

        bool Set_id(STRING id);
        STRING Get_id();

	bool Set_name(STRING id);
	STRING  Get_name();

	bool Register_tag();

	static TAG *New_tag(STRING id);

	static bool  Registered_tag(STRING id);

	static void Destroy_registered_tags();

	__use_tag_funcs
	__use_private_struct

	UBYTE *Alloc_buffer(int bsize);
	UBYTE *Get_buffer(int *bsize);

};

Set_id() : assegna un id di identificazione del tipo di tag; ogni classe tag possiede un idunivoco; in pratica non si usa direttamente questa funzione, si utilizza la macro _tag_register che descriveremo fra poco, e che, inserita nel costruttore di una classe derivata da TAG, la rende disponibile per il salvataggio e richiamo da file;

Get_id() : rimanda l’identificatore della classe; I’id della classe può essere usato per verificare la sua registrazione dell’applicazione.

Set_name() e Get_name(): le due funzioni definiscono e rimandano il nome assegnato ad una tag istanziata; la ricerca del tag in una tag_list è effettuata attraverso il nome assegnato.

Register_tag(): Per essere inseribile in una tag_list la classe TAG deve essere appositamente registrata nell’applicazione; la registrazione permette il riconoscimento automatico dei tag in fase di scrittura e lettura file ( oltre ad altri automatismi la cui conoscenza non è per ora necessaria); Il modo migliore per effettuare la registrazione è l’inserimento nel costruttore della classe della macro  _tag_register  che effettua sia l’assegnazione dell’identificatore della classe, sia la sua registrazione (si consiglia di inserire questa macro alla fine del codice del costruttore della classe).

La classe TAG contiene un gruppo di funzioni statiche che istanziano  TAG registrati attraverso l’id, o controllano che un particolare id corrisponda ad un tipo di TAG registrato:

 New_tag(STRING id) : istanzia un TAG dato il suo id; se l’id non corrisponde ad un TAG registrato, rimanda 0; poichè viene istanziata una classe,  il suo rilascio può essere fatto in due modi: se non utilizzato altrimenti usare delete; se invece il tag è inserito in una tag_list, il distruttore della stessa rilascerà tutti i tag contenuti;

Registered_tag(STRING id) : controlla che l’id corrisponda ad un TAG registrato, ed in questo caso rimanda true;

Destroy_registered_tags(); distrugge la lista dei TAG registrati in precedenza nel software;  la funzione è usata solo internamente dalle classi del namespace TAGS e non deve mai essere usata fuori da questo contesto.

Funzioni e metodi virtuali della classe

la macro __use_tag_funcs è così definita:

#define __use_tag_funcs  __use_file_io virtual TAG  *New(); 

serve a dichiarare nel corpo di definizione delle classi derivate da TAG un gruppo di funzioni virtuali che devono essere sempre definite per ciascuna nuova classe:

New()  è una funzione che istanzia la classe, rimandandone il puntatore

Read(DataFile *fd)  e Write(DataFile *fd), sono le solite funzioni standard per effettuare la lettura e scrittura di classi su un file  (ricordiamo che praticamente su tutte le classi di Colibri che devono essere salvate/lette su file sono definite le due funzioni e la classe DataFile rende disponibili la  scrittura e lettura sul file).

Le funzioni Alloc_buffer e Get_buffer sono  usate solo dalla classe TAG_list, e non è necessario (per ora) conoscerne l’utilizzo;