-----------------------------------------------

                 ProgED V1.0 by Giovanni Lambiase (C) 1995

                         Note per i programmatori

              -----------------------------------------------


-------------------------
 1. Strutture principali
-------------------------

    In questo paragrafo descriveremo tutte le strutture utili per un
utente che indenta scrivere un cliente API. Le strutture PEDWindow e Prefs
descrivono, rispettivamente, le finestre aperte dal ProgED e le preferenze
globali. Seguono altre strutture più piccole ma non meno importanti, come
la struttura che definisce le linee del testo o i programmi interni
(creati dal pannello di programmazione del ProgED). Il commento ad ogni
campo inizia con i caratteri "^--" ).




    struct PEDWindow
    {
	struct Window	*Window;

        ^-- Puntatore alla finestra intuition. Se la finestra è chiusa
            (vedi comando interno FREEZE) vale NULL.

	struct Gadget	*GadgetScrollX,
			*GadgetScrollY,
			*GadgetUpArrow,
			*GadgetDownArrow,
			*GadgetLeftArrow,
			*GadgetRightArrow;

	^-- Puntatori ai gadget di scorrimento e alle relative frecce.

	struct Image	*ImageUpArrow,
			*ImageDownArrow,
			*ImageLeftArrow,
			*ImageRightArrow;

	^-- Immagini delle quattro frecce attaccate ai gadget di scroll.

	int		 OldSx,
			 OldSy,

	^-- Ascissa (colonna) e ordinata (linea) del primo carattere in alto
            a sinistra nella finestra PRECEDENTI quelle attuali. Questi valori
            non considerano i fold precedenti che vengono considerati come una
            singola linea.

			 Sx,
			 Sy;

	^-- Ascissa (colonna) e ordinata (linea) del primo carattere in alto
            a sinistra nella finestra ATTUALI. Questi valori non considerano
            i fold precedenti che vengono considerati come una singola linea.

	struct Line	*FirstLine,
			*LastLine;

	^-- Puntatore alla prima ed alla ultima linea del testo.

	LONG		 MaxCol,

	^-- Copia di Prefs.MaxCol (Num. max di colonne nel testo).

			 NumCol,

	^-- Num. di colonne nella finestra (larghezza in caratteri).

			 MaxLine,

	^-- Num. di linee nel testo (non tiene conto dei fold).

			 NumLine;

	^-- Num. di linee nella finestra (altezza in linee).

	ULONG		 Size;

	^-- Dimensione in byte del testo in memoria.

	WORD		 Left,
			 Top,
			 Width,
			 Height;

	^-- Variabili temporanee. Mantengono le dimensioni e la posizione
            della finestra mentre è chiusa.

	WORD		 ZoomInfo[4];

	^-- Array relativo al gadget Zoom di intuition.

	char		 FileName[200];

	^-- Nome del file (completo) caricato in memoria.

	char		 Title[200];

	^-- In questa zona ProgED costruisce il titolo della finestra.

	LONG		 CursorCol;
	LONG		 CursorLine;

	^-- Posizione del cursore nel testo (colonna/linea). Non tiene
            conto dei fold.

	LONG		 LastCursorCol;

	^-- Ultima colonna in cui abbiamo scritto qualcosa.

	struct Line	*Line;

	^-- Puntatore alla linea su cui si trova il cursore.

	UWORD		 RealNumCol;

	^-- Num colonne reali (numero di bytes,un TAB è pari ad 1).

	UWORD		 LogicNumCol;

	^-- Num colonne logiche (tiene conto degli spazi relativi ai TAB).

	UWORD		 FWidth,
			 FHeight,

	^-- Larghezza e altezza (in pixel) del font utilizzato.

			 FBase,

	^-- Baseline del font utilizzato.

			 WOffsetX,
			 WOffsetY;

	^-- Offset X ed Y della finestra (dovuto ai bordi sup. e sinistro).

	struct RastPort *RP;

	^-- Rastport della finestra (Window->RPort).

	UBYTE		 Ins;

	^-- TRUE=modo inserimento,FALSE=modo overwrite.

	UBYTE		 MLine,

	^-- TRUE=blocco con opzione LINE, FALSE=altrimenti.

			 Block;

	^-- Tipo blocco: NO_SEL,BLOCK_SEL,COLBLOCK_SEL (vedi file "Ped.h").

	LONG		 BlockLine,
			 BlockCol;

	^-- Inizio blocco marcato (linea e colonna).

	ULONG		 Changes;

	^-- Cambi dall'ultimo salvataggio.

	struct Event	 *Events;

	^-- Puntatore ad un array di strutture Events. Ogni struttura
            mantiene un evento per la coda di UNDO/REDO. Il numero di
            strutture è dato nel successivo campo UndoLevels.

	LONG		 LastEvent;

	^-- Ultimo evento nella coda.

	ULONG		 NumEvent,

	^-- Numero di eventi nella coda.

			 NumRedo,

	^-- Numero di REDO possibili.

			 UndoLevels;

	^-- Lunghezza della coda.

	char		*CuttedLine;

	^-- Clipboard linea (vedi comando LINE CUT).

	struct Marker	Marker[MAXMARKER];

	^-- Vettori di marker. Ogni marker detiene una posizione nel testo.

	struct Folder	*Folder;

	^-- Puntatore ad una lista di folder. Ogni struttura mantiene le
            informazioni relative ad un fold.

	int		 LinesFolded;

	^-- Numero di linee chiuse nei vari fold.

	int		 NumFolds;

	^-- Numero totale di fold.

	UBYTE		 Frozen;

	^-- TRUE=finestra chiusa, FALSE=aperta.

	ULONG		 Locked;

	^-- Se >0 la finestra è bloccata dagli handler.

	ULONG		 AutoSave;

	^-- Contatore autosave (in secondi). Decresce fino a 0.

	struct Line	*OldLine;
	UBYTE		*LineBuffer,
			*Pun,
			 InsLine,
			 Warn;

	^-- Dati utili SOLO durante il load dal PED_DISK. Non manipolare.

	UBYTE			 OldKeys[MAXTEMPLATE];
	UBYTE			 PunOldKeys;

	^-- Dati utili per i template (ricordano gli ultimi tasti battuti).

	struct DateStamp	DateStamp;

	^-- Data ultima modifica (utile per gli handler).

	struct PEDWindow	*NextWindow;

	^-- LINK alla prossima finestra del ProgED.

	ULONG			 UserData[16];

	^-- Dati utente. Se hai bisogno di memorizzare dati per ogni
            finestra utilizza questi campi.
    }




    struct Prefs
    {
	ULONG		ScreenMode;
	UWORD		ScreenWidth;
	UWORD		ScreenHeight;
	UWORD		ScreenOverscanType;
	UBYTE		ScreenDepth;
	UBYTE		ScreenAutoScroll;

	^-- Caratteristiche dello schermo del ProgED: DisplayID,larghezza,
            altezza,tipo overscan,profondità,flag autoscroll.

	UWORD		ScreenColors[MAXCOLOR];

	^-- Primi MAXCOLOR colori dello schermo. Tali colori vengono
            memorizzati e salvati da ProgED.

	char		ScreenFontName[MAXFONTNAM+1];
	UWORD		ScreenFontSize;

	^-- Nome e dimensione del font per lo schermo.

	char		MenuFontName[MAXFONTNAM+1];
	UWORD		MenuFontSize;

	^-- Nome e dimensione del font per i menù.

	char		TextFontName[MAXFONTNAM+1];
	UWORD		TextFontSize;

	^-- Nome e dimensione del font per i testi.

	char		GadgetFontName[MAXFONTNAM+1];
	UWORD		GadgetFontSize;

	^-- Nome e dimensione del font per i gadget. ATTENZIONE solo
            font di dimensione 8 !!!!!!!!!!!!!!!

	UWORD		MaxCol;

	^-- Numero massimo di colonne per i testi. Ogni finestra, all'apertura,
            copia nel suo omonimo campo questo valore.

	UBYTE		AltStep;

	^-- Salto righe quando si utilizza il comando UP STEP (o DOWN STEP).

	UBYTE		Tab;

	^-- Dimensione TAB in caratteri.

	UBYTE		LeftBorder;
	UBYTE		RightBorder;
	UBYTE		TopBorder;
	UBYTE		BottomBorder;

	^-- Bordi oltre il quale il cursore provoca uno scroll.

	UBYTE		UseKeyWordColors;

	^-- TRUE=attiva l'uso dei colori per le parole chiavi,FALSE=disabilita.

	UBYTE		KeyAlpha[256];

	^-- NON MANIPOLARE!!!!!!!!!!!!!!!!!!!!!! Grazie.

	char		**KeyWord;

	^-- Puntatore al vettore di (char *) contenente le parole.

	int		NumKeyWord;

	^-- Numero di parole nel vettore.

	char		GestColorOff,
			GestColorOn;

	^-- Caratteri di disattivazione ed attivazione della gestione.

	UBYTE		UseCommentColors;

	^-- TRUE=Attiva l'uso dei colori per i commenti,FALSE=disabilita.

	UWORD		CheckColorLines;

	^-- Max num. di linee di un commento (0=senza limite).

	UBYTE		Comment1Pen,

	^-- Penna da utilizzare per i commenti tra più linee.

			Comment2Pen;

	^-- Penna da utilizzare per i commenti fino a fine linea.

	char		Comment1On[MAXCOMMENT+1],
			Comment1Off[MAXCOMMENT+1],

	^-- Stringhe iniziali e finali dei commenti su più linee.

			Comment2On[MAXCOMMENT+1];

	^-- Stringa iniziale dei commenti fino a fine linea.

	UBYTE		BackPen;

	^-- Penna sfondo schermo.

	UBYTE		PaperPen;

	^-- Penna carta (sfondo finestre).

	UBYTE		DefTextPen;

	^-- Penna testo.

	UBYTE		PaperBlockPen;

	^-- Penna blocchi marcati.

	UWORD		ScreenPens[13];

	^-- Penne intuition dello schermo del ProgED.

	UBYTE		Clipboard;

	^-- Clipboard standard.

	UBYTE		EraseRight;

	^-- TRUE=attiva cancellazione spazi e TAB a fine linea.

	UBYTE		ShowCursorPos;

	^-- TRUE=Mostra la posizione (linea e colonna) del cursore nella
            barra del titolo della finestra.

	UBYTE		ShowPathName;

	^-- TRUE=Mostra il path completo del file,FALSE=solo il nome.

	UBYTE		AutoArrangeVer;

	^-- TRUE=Arrangia verticalmente le finestre. Questo flag è
            mutuamente esclusivo col successivo.

	UBYTE		AutoArrangeHor;

	^-- TRUE=Arrangia orizzontalmente le finestre. Questo flag è
            mutuamente esclusivo col successivo.

	UBYTE		Favourite;

	^-- TRUE=Favorisci la finestra attiva dandole mezzo schermo.

	UBYTE		UseSetDefPubScr;

	^-- TRUE=Setta lo schermo del ProgED come schermo pubblico.

	UBYTE		UseClock;

	^-- TRUE=Attiva l'orologio sullo schermo del ProgED.

	UBYTE		Backup;

	^-- TRUE=Crea un backup ad ogni salvataggio.

	UBYTE		Save;

	^-- TRUE=Salvataggio sicuro,FALSE=normale.

	UBYTE		SaveRefs;

	^-- TRUE=Salva,insieme al file, i riferimenti contenuti nel file
            stesso.

	UBYTE		UnfoldOnGotoMarker;
	UBYTE		UnfoldOnGotoLine;
	UBYTE		UnfoldOnGotoByte;
	UBYTE		UnfoldOnGotoScan;

	^-- TRUE=Effettua un unfold quando il ProgED salta ad una linea dopo:
            1) un salto ad un marker, 2) un salto ad una linea, 3) un salto
            ad un byte, 4) un salto ad un riferimento

	UBYTE		BlankBorders;

	^-- TRUE=Elimina i bordi degli schermi (rendili neri).

	UBYTE		AutoFold;

	^-- TRUE=Auto-fold al caricamento.

	char		SearchFoldFileName[MAXFOLDFUNCNAME+1];

	^-- Nome della funzione di ricerca dei fold.

	LONG		DefBits;

	^-- Bits da dare ai file salvati (bisogna effettuare uno XOR con
            0x000F prima di effettuare l'operazione).

	char		DefComment[MAXCOMMENT2+1];

	^-- Commento da dare ai file salvati.

	UBYTE		CreateIcons;

	^-- TRUE=Crea icone per i file salvati.

	UBYTE		UseKeyWordInd;

	^-- TRUE=Abilita l'indentazione automatica.

	char		**KeyWordInd;

	^-- Puntatore ad un vettore di parole. Ogni parola termina con uno
            dei caratteri IND_xxx che specifica il tipo di indentazione.

	int		NumKeyWordInd;

	^-- Numero di parole nel vettore.

	UWORD		IndJump;

	^-- Colonne per livello d'indentazione.

	UBYTE		SeparateItems;

	^-- TRUE=Separa i menù con una barra.

	struct MyMenu	*Menu;

	^-- Puntatore ad una lista che definisce i menù.

	char		HelpFile[MAXFILENAME+1];

	^-- Nome file della guida per i menù.

	struct MyKey	*Key;

	^-- Puntatore ad una lista che definisce i tasti.

	UBYTE		UseAppIcon;

	^-- TRUE=Mostra la AppIcon quando sei iconificato.

	UBYTE		UseMenuItem;

	^-- TRUE=Appendi un item al menù "Strumenti" del WB quando sei
            iconificato.

	UBYTE		UseAutoSave;

	^-- TRUE=Attiva autosalvataggio.

	UWORD		MinAutoSave;

	^-- Numero di minuti tra gli autosave.

	UBYTE		AutoReLoad;

	^-- TRUE=Ricarica, alla partenza, tutti i testi che erano in
            memoria nella sessione precedente.

	UBYTE		MouseBlanker;

	^-- TRUE=Attiva il mouseblanker.

	UBYTE		FastLoad;

	^-- TRUE=Attiva il caricamento veloce,FALSE=normale.

	char		**APIClients;

	^-- Puntatore ad un vettore di (char *). Ogni stringa è il nome
            (su disco) di un cliente API.

	int		NumAPIClients;

	^-- Numero di stringhe nel vettore precedente (numero clienti API).

	char		StartUpMacro[MAXSTARTUPMACRO];

	^-- Macro REXX iniziale.

	char		PreIconifyMacro[MAXSTARTUPMACRO];

	^-- Macro REXX pre-iconificazione.

	char		PostIconifyMacro[MAXSTARTUPMACRO];

	^-- Macro REXX post-iconificazione.

	struct MyScan	*Scan;

	^-- Puntatore ad una lista contenente gli scanner attualmente
            caricati.

	struct MyTemplate	*Template;

	^-- Puntatore ad una lista contenente i template.

	UBYTE		UseTemplate;

	^-- TRUE=Attiva gestione dei template.

	UBYTE		UseRightGadget;

	^-- TRUE=Attiva il gadget di scrolling destro.

	UBYTE		UseBottomGadget;

	^-- TRUE=Attiva il gadget di scrolling inferiore.

	LONG		LeftExtraSpace,
			RightExtraSpace,
			TopExtraSpace,
			BottomExtraSpace;

	^-- Spazi liberi (in pixel) da lasciare in alto,basso,destra e
            sinistra quando le finestre vengono riaggiustate.

	char		**DictWord;

	^-- Puntatore ad un vettore di (char *).Ogni stringa è una delle
            frasi presenti nel dizionario.

	int		NumDictWord;

	^-- Numero di parole nel dizionario.

	UBYTE		UseAutoCase;

	^-- TRUE=Attiva autocase (aggiusta maius./minus. delle parole
            presenti nel dizionario).

	UBYTE		CheckPar;

	^-- TRUE=Attiva controllo delle parentesi '(' ')' quando il
            cursore lascia la linea.

	UBYTE		FastMode;

	^-- TRUE=Attiva modo veloce,FALSE=modo normale.

	char		**Ref;

	^-- Puntatore ad un vettore di (char *). Ogni stringa contiene un
            pattern o una directory in cui cercare i riferimenti durante
            la creazione della mappa.

	int		NumRef;

	^-- Numero di stringhe nel vettore precedente.

	UBYTE		RAMReference;

	^-- TRUE=Mantieni la mappa dei riferimenti in RAM.

	UBYTE		ReferenceCase;

	^-- TRUE=Ricerca dei riferimenti case-sensitive,FALSE=non case-sen.

	char		ReferenceFile[MAXREFNAME+1];

	^-- Nome del file contenente la mappa dei riferimenti.

	char		**HuntPath;

	^-- Puntatore ad un vettore di stringhe. Ogni stringa rappresenta
            una directory in cui ricercare i file quando l'utente attiva
            l'apposito comando.

	int		NumHuntPath;

	^-- Numero di stringhe presenti nel vettore precedente.

	UBYTE		UseRTSysReq;
	UBYTE		UseRTFileReq;
	UBYTE		UseRTFontReq;
	UBYTE		UseRTScreenReq;

	^-- TRUE=Usa, rispettivamente, le richieste, i file-requester,
            i font-requester, e i screenmode-requester della ReqTools.library.
            Ponendo a FALSE uno dei flag ProgED utilizza la Asl.library.

	char		**ProjectFiles;

	^-- Puntatore ad un vettore di stringhe. Ogni stringa è il nome
            di uno dei file nel progetto.

	int		NumProjectFiles;

	^-- Numero di file nel progetto (numero di stringhe nel vettore
            precedente).

	UWORD		Left,
			Right;

	^-- Margini sinistro e destro per le operazioni di raggruppamento
            dei blocchi.

	char		XpkLib[5];

	^-- Nome libreria XPK da utilizzare per i salvataggi con la
            XpkMaster.library.

	UBYTE		XpkMode;

	^-- Modo XPK da utilizzare per i salvataggi con la XpkMaster.library.

	int		XpkPos;

	^-- NON MANIPOLARE!!!!!!!!!! Grazie.

	char		XpkPassWord[52];

	^-- Password per le librerie XPK che la richiedono.

        ULONG		UndoLevels;

	^-- Numero di livelli di UNDO. Quando ProgED apre una nuova finestra
            copia questo valore nel campo UndoLevels della finestra e crea
            la coda di UNDO della lunghezza data.
    }




    struct Line
    {
	char		*Buffer;

	^-- Testo della linea (termina con zero)

	struct Line	*PrevLine,
			*NextLine;

	^-- Puntatori alla linea precedente e successiva del testo

	struct Folder	*Folder;

	^-- Se questa linea è chiusa in un fold questo puntatore punta
            alla relativa struttura Folder (che si trova nella apposita
            lista presente nella finestra).
    }




    struct MyTemplate
    {
	char			 Template[MAXTEMPLATE+1];

	^-- Stringa che attiva questo template.

	struct MyProgram	*Prg;

	^-- Programma interno da eseguire all'attivazione.

	struct MyTemplate	*NextTemplate;

	^-- Puntatore alla prossima struttura della lista.
    }



    struct MyScan
    {
	BPTR		 SegList;

	^-- Puntatore BPTR alla seglist della funzione caricata.

	ULONG		(* ASM ScanFunction)(RG(a0) char *,RG(a1) char *);

	^-- Puntatore alla funzione assembler contenuta nella seglist
            precedente (è pari all'indirizzo precedente più 4 bytes).

	char		 ScanExtension[MAXEXTSCAN+1],

	^-- Pattern AmigaDOS che individua i file su cui deve operare lo
            scanner.

			 Name[MAXSCANNAME+1];

	^-- Nome (su disco) della funzione.

	struct MyScan	*NextScan;

	^-- Puntatore alla prossima struttura della lista.
    }




    struct MyProgram
    {
	char			*String,

	^-- Puntatore alla stringa del comando.

				*Dir,

	^-- Eventuale directory corrente (solo per TYPE_SHELL/TYPE_AREXX).

				*Output;

	^-- Eventuale file d'uscita (solo per TYPE_SHELL/TYPE_AREXX).

	UBYTE			 Type;

	^-- Tipo del comando (vedi costanti TYPE_xxxxx).

	UBYTE			 Async;

	^-- TRUE=comando asincrono,FALSE=sincrono. Vale solo per i
            comandi di tipo TYPE_SHELL. è automaticamente TRUE per
            i comandi TYPE_AREXX.

	struct MyProgram	*NextProgram;

	^-- Puntatore al prossimo comando del programma interno.
    }




    struct MyMenu
    {
	char			 Name[MAXMENUNAME+1];

	^-- Nome di questo menù.

	struct MyItem		*Items;

	^-- Puntatore alla lista di item relativi a questo menù.

	struct MyMenu		*NextMenu;

	^-- Puntatore al prossimo menù della lista.
    }

    struct MyItem
    {
	char			 Name[MAXMENUNAME+1];

	^-- Nome di questo item.

	char			 Key[MAXMENUNAME+1];

	^-- Tasto (o stringa) di attivazione di questo item.

	struct MySub		*Subs;

	^-- Puntatore alla lista di subitem relativi a questo menù.

	struct MyProgram	*Prg;

	^-- Puntatore al programma interno da eseguire all'attivazione
            di questo item.

	UBYTE			 CheckType;	/* NB: DEVE RIMANERE DOPO Prg */

	^-- Tipo di checkmark da assegnare a questo item. Vedi costanti
            CHECK_xxxx.

	struct MyItem		*NextItem;

	^-- Puntatore al prossimo item.
    }

    struct MySub
    {
	char			 Name[MAXMENUNAME+1];

	^-- Nome di questo subitem.

	char			 Key[MAXMENUNAME+1];

	^-- Tasto (o stringa) d'attivazione di questo subitem.

	struct MyProgram	*Prg;

	^-- Programma interno da eseguire all'attivazione del subitem.

	UBYTE			 CheckType;	/* NB: DEVE RIMANERE DOPO Prg */

	^-- Tipo di checkmark da assegnare a questo item. Vedi costanti
            CHECK_xxxx.

	struct MySub		*NextSub;

	^-- Puntatore al prossimo subitem.
    }




    struct MyKey
    {
	ULONG			 Qual,
				 Code;

	^-- Identificano il tasto a cui rispondere (corrispondono ai campi
            Code e Qualifier di un messaggio intuition).

	struct MyProgram	*Prg;

	^-- Programma interno da eseguire all'attivazione del tasto.

	struct MyKey		*NextKey;

	^-- Prossimo tasto nella lista.
    }

    struct Event
    {
	UBYTE		 Type;
	UBYTE		 Arg1;
	char		*Arg2;
	ULONG		 Arg3,
			 Arg4,
			 Arg5,
			 Arg6,
			 Arg7;
	LONG		 Col,
			 Line;
    }

    ^-- Questa struttura è volutamente lasciata senza commento.




    struct Folder
    {
	char		 Name[MAXFOLDNAME+1];

	^-- Nome assegnato dalla funzione di ricerca a questo fold (viene
            mostrato sulla linea che rappresenta il fold stesso).

	long		 Num;

	^-- Numero di linee di cui è composto il fold.

	struct Line	*Line;

	^-- Linea alla quale si trovava il cursore al momento della
            chiusura.

	long		 Col;

	^-- Colonna alla quale si trovava il cursore al momento della

	struct Line	*Start,
			*End;

	^-- Linea iniziale e finale del fold.

	struct Folder	*NextFolder;

	^-- Puntatore al prossimo fold della lista.
    }




    struct Marker
    {
	struct Line	*Line;

	^-- Puntatore alla linea relativa alla posizione memorizzata. Se la
            linea viene cancellata ProgED porta, automaticamente, questo
            valore a NULL. In questo caso un eventuale salto porta il
            cursore alla prima linea del testo.

	long		 Col;

	^-- Colonna relativa alla posizione memorizzata.
    }




------------
 2. Scanner
------------

    Uno scanner deve essere scritto tramite una funzione assembler o una
funzione C che prende gli argomenti nei registri. Il codice risultante
deve essere linkato SENZA alcun modulo di startup, in modo tale che la
prima locazione eseguibile sia l'inizio della funzione scritta. La
funzione di ricerca riceve due argomenti nei seguenti registri:

    A0: Indirizzo della linea su cui effettuare la ricerca. Punta ad una
        stringa terminata con 0.

    A1: Indirizzo del buffer che conterrà il riferimento, se trovato.

    La funzione deve ritornare nel registro D0 la lunghezza della stringa
creata nel buffer puntato da A1. Nel caso la funzione non abbia trovato
nulla deve ritornare 0.

    NOTA: è necessario salvare tutti i registri all'ingresso della
          funzione e ripristarli all'uscita.



-----------
 3. Folder
-----------

    Una funzione di ricerca dei fold deve essere scritta tramite una funzione
assembler o una funzione C che prende gli argomenti nei registri. Il codice
risultante deve essere linkato SENZA alcun modulo di startup, in modo tale
che la prima locazione eseguibile sia l'inizio della funzione scritta. La
funzione di ricerca riceve due argomenti nei seguenti registri:

    A0: è l'indirizzo della struttura PEDWindow relativa al testo su
        cui effettuare la ricerca.

    D0: Contiene il numero della colonna su cui è posizionato il cursore.
        (0=prima colonna).

    D1: Contiene il numero della linea su cui è posizionato il cursore.
        Tale numero è assoluto. Ciò significa che non tiene conto dei
        fold eventualmente presenti nel testo. (0=prima linea).

    A1: Contiene l'indirizzo di una long-word. In tale long-word la funzione
        deve scrivere il numero della linea iniziale del fold, se trovato.
        Anche in questo caso la funzione non deve considerare eventuali
        fold già presenti nel testo. (0=prima linea).

    A2: Contiene l'indirizzo di una long-word. In tale long-word la funzione
        deve scrivere il numero della linea finale del fold, se trovato.
        Anche in questo caso la funzione non deve considerare eventuali
        fold già presenti nel testo. (0=prima linea).

    A3: Punta ad un buffer in cui la funzione deve scrivere la stringa
        che ProgED scriverà a fianco dell'indicatore ">FOLD". Generalmente
        il nome della funzione C, ecc.

    La funzione deve ritornare in D0 il valore 1 se ha trovato un fold, 0
altrimenti. Nel primo caso la funzione deve anche fornire, tramite A1 e A2
i numeri di linea iniziali e finali del fold e, tramite A3, la stringa
rappresentante il fold. è necessario,infine, salvare tutti i registri
all'ingresso della funzione e ripristinarli all'uscita.

    NOTA: la funzione 'FOLD ALL' viene eseguita eseguendo una chiamata
alla funzione su tutte le linee (dalla prima all'ultima) e con il
numero di colonna pari a 0 (prima colonna).



----------------
 4. Clienti API
----------------

    ProgED consente ad applicazioni esterne (chiamate "clienti") di
 "agganciarsi" ad esso. Un cliente API è semplicemente un normale
programma (scritto in qualsiasi linguaggio). Tale programma deve
essere scritto in modo tale da "registrarsi" presso il ProgED. Ciò
consente al ProgED di tracciare tutti i clienti e di mandar loro
messaggi sulle operazioni che devono effettuare.

I messaggi che un cliente deve inviare a ProgED (nella sua porta
API di nome "PED_API") hannno la seguente struttura:



    struct APIMessage
    {
        struct Message     am_Message;
        ULONG              am_MsgType,
                           am_MsgArg[10],
                           am_RC;
    }

    am_Message:

         è un campo contenente un messaggio standard Exec.

    am_MsgType:

         Contiene il tipo di messaggio da inviare.

    am_MsgArg[]:

         è un vettore contenente un massimo di 10 argomenti
         dipendenti dal tipo del messaggio

    am_RC:

         è il codice di ritorno che ProgED restituisce al cliente
         per informarlo sul successo dell'operazione.




    I tipi di messaggi che un cliente può spedire a ProgED sono, per ora:

    PED_API_REGISTER:

          Registra un cliente presso ProgED. Richiede un puntatore ad una
          struttura di tipo APIClient in am_MsgArg[0]. Non ritorna nessun
          risultato in am_RC.

    PED_API_UNREGISTER:

          Informa ProgED che il cliente vuole andarsene (!?). Richiede lo
          STESSO puntatore dato al momento della registrazione, con il
          messaggio PED_API_REGISTER, in am_MsgArg[0]. Non ritorna nessun
          risultato in am_RC.

    PED_API_ADD_INTERNAL_COMMAND:

          Consente di espandere le funzionalità del ProgED aggiungendo un
          nuovo comando interno. A tale scopo è necessario allocare e
          riempire una struttura ArexxExtCmds e fornire il suo puntatore
          in am_MsgArg[0]. Nessun risultato in am_RC.

    PED_API_REM_INTERNAL_COMMAND:

          Rimuove un comando precedentemente aggiunto tramite il messaggio
          PED_API_ADD_INTERNAL_COMMAND. è necessario fornire in am_MsgArg[0]
          lo STESSO puntatore dato al momento dell'aggiunta del comando.
          Non ritorna risultati in am_RC.

    PED_API_GET_ACTIVE_WINDOW:

        Ottiene, in am_RC, l'indirizzo della struttura PEDWindow associata
        alla finestra attualmente attiva.

    PED_API_GET_WINDOW_LIST:

        Ottiene, in am_RC, l'indirizzo iniziale della lista di strutture
        PEDWindow corrispondenti ai testi in memoria.

    PED_GET_SCREEN_ADDRESS:

        Ottiene, in am_RC, l'indirizzo dello schermo del ProgED. Se il ProgED
        è attualmente iconificato ritorna NULL.

    PED_GET_PREFS_ADDRESS:

        Ottiene, in am_RC, l'indirizzo della struttura Prefs.

    PED_GET_PUBSCRNAME:

        Ottiene, in am_RC, un puntatore al nome dello schermo pubblico
        aperto dal ProgED.

    NOTA: La struttura ArexxExtCmds (e tutti gli oggetti a cui puntano i
          suoi campi), fornita al momento dell'aggiunta del comando, deve
          rimanere valida in memoria. è possibile riutilizzarla (o
          liberare la memoria associata solo DOPO aver utilizzato un
          messaggio di tipo PED_REM_INTERNAL_COMMAND.
          Lo stesso vale per la struttura APIClient utilizzata per il
          messaggio PED_API_ADD_INTERNAL_COMMAND. In questo caso è
          possibile riutilizzare la struttura dopo il corrispondente
          messaggio PED_API_REM_INTERNAL_COMMAND.




    I messaggi che ProgED può inviare ad un cliente sono, per ora:

    PED_API_SHOW:

        ProgED ha riaperto il suo schermo. L'indirizzo dello schermo
        può essere ottenuto nel campo am_MsgArg[0]. Nel campo am_MsgArg[1],
        invece, si trova un puntatore al nome dello schermo pubblico
        utilizzato. Il cliente puo' utilizzare queste due informazioni
        per aprire eventuali finestre sullo schermo del ProgED. Questo
        messaggio viene spedito solo se, al momento della registrazione,
        il cliente ha settato il flag NOTIFY_ON_SHOWHIDE.

    PED_API_HIDE:

        ProgED stà per chiudere il suo schermo. Questo messaggio viene
        spedito solo se, al momento della registrazione, il cliente ha
        settato il flag NOTIFY_ON_SHOWHIDE.


    PED_API_KEY:

        L'utente ha battuto un tasto. Il cliente può ottenere la struttura
        IntuiMessage relativa leggendo il campo MsgArg[0]. Tale campo
        conterrà il puntatore alla struttura IntuiMessage contenente il
        messaggio di tipo rawkey ricevuto dal ProgED. Questo messaggio
        viene spedito solo se, al momento della registrazione, il cliente
        ha settato il flag NOTIFY_ON_KEY. 
        NOTA: In ogni caso, al termine della gestione di questo messaggio,
        ProgED eseguirà l'azione legata al tasto. Inoltre il cliente
        NON DEVE modificare il messaggio stesso, perchè è un messaggio
        proveniente da Intuition!

    PED_API_QUIT:

        ProgED sta per terminare. Alla ricezione di questo messaggio (che
        viene SEMPRE inviato a prescindere dai flag NOTIFY_xxx) il cliente
        deve chiudere le eventuali finestre e terminare. E' VIETATO
        UTILIZZARE LA PORTA API DOPO LA RICEZIONE DI QUESTO MESSAGGIO !!!!!
        Questo implica che, dopo la ricezione di questo messaggio, il
        cliente NON DEVE tentare di togliere la registrazione e/o la
        definizione di comandi esterni.



    Qui di seguito sono riportate le spiegazioni riguardanti i campi delle
diverse strutture utilizzate.


    struct APIClient
    {
        struct MsgPort          *ac_ClientPort;
        ULONG                    ac_Notify;
        char                    *ac_name;
        struct APIClient        *ac_Next;
    }

    ac_ClientPort:

        Indica l'indirizzo di una porta messaggi a cui ProgED invierà i
        messaggi informativi al cliente. Questo tipo di messaggi verrà
        spiegato successivamente.

    ac_Notify:

        Indica quali tipi di messaggi il cliente vuole ricevere dal ProgED.
        Gli unici tipi di messaggi selezionabili attualmente sono indicati
        dal flag NOTIFY_ON_SHOW_HIDE. 

    ac_Name:

        Punta al nome del cliente.

    ac_Next:

        Porre a NULL. Conterrà il successore cliente della lista interna
        del ProgED.




    struct ArexxExtCmds
    {
        UBYTE                    External;
        char                    *Name;
        char                    *Template;
        void                    *Defaults[MAXREXXARGS];
        LONG ASM                (*CommFunc)( RG(a0) struct CommandData *);
        struct ArexxExtCmds     *NextCmd;
    }

    External:

        Indica che il comando è gestito da un cliente. Porre SEMPRE a TRUE.

    Name:

        Nome del comando. Specificare sempre in lettere maiuscole.

    Template:

        è il template AmigaDOS del comando.

    Default[]:

        Indica il vettore di puntatori che deve essere passato alla
        funzione ReadArgs della dos.library. Deve contenere i valori
        di default dei parametri del template. Per ulteriori informazioni
        leggere la documentazione della funzione ReadArgs.

    CommFunc:

        Indica il puntatore alla funzione che realizza il comando. Tale
        funzione deve essere scritta in assembler (o ricevere i parametri
        come una funzione assembler). Essa deve ricevere un puntatore ad
        una struttura CommandData in A0 e ritornare il codice d'errore
        risultante dall'esecuzione in D0. In seguito analizzeremo la
        struttura CommandData.

    NextCmd:

        Porre a NULL. ProgED ne modificherà il valore portandolo a
        puntare al prossimo comando fornito dallo stesso cliente o da
        un altro.




    struct CommandData
    {
        char              *CommandLine;
        void             **CommandArgs;
        struct MyWindow   *CurrentWindow,
                          *FirstWindow;
        struct Prefs      *CurrentPrefs;
        LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
    }

    CommandLine:

        Punta ad una stringa riportante l'intera linea di comando riguardante
        il comando.

    CommandArgs:

        Punta ad un vettore di (void *). Ogni puntatore deve essere utilizzato
        secondo le norme dettate dalla ReadArgs. Questo vettore, infatti, è
        il risultato della applicazione della stessa funzione alla linea di
        comando (tenendo presente i default dati nella struttura ArexxExtCmds).

    CurrentWindow:

        Indica il puntatore alla struttura PEDWindow indicante la finestra
        attualmente attiva.

    FirstWindow:

        Indica il puntatore alla prima struttura PEDWindow della lista di
        finestre mantenuta dal ProgED.

    ExecuteInternalCommand:

        è un puntatore ad una funzione assembler. Chiamando questa
        funzione (specificando in A0 il puntatore ad una stringa) è
        possibile eseguire i comandi interni del ProgED. A tale scopo
        la stringa puntata da A0 deve contenere la linea di comando
        desiderata. In D0 viene ritornato il codice d'errore risultante.

        NOTA: Non utilizzare la porta ARexx di ProgED per eseguire i
        comandi interni! Così facendo, infatti, si bloccherebbero
        sia ProgED che il cliente. Ciò è dovuto al fatto che, mentre
        ProgED esegue la funzione che implementa il comando, NON PUò
        rispondere ai messaggi provenienti da sè stesso!



-------------------
 5. Funzioni utili
-------------------

    Le funzioni C che seguono sono utili per la scrittura di folder e
scanner. Esse riguardano la ricerca di linee. Potete utilizzarle
tagliandole da questo testo e inserendole nei vostri programmi.



/*****
 *
 * FUNZIONE:	struct Line *SearchLine(struct Line *line,int y)
 *
 * SCOPO:	Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
 *		dalla prima linea del file data da line.
 *		NB: Tiene conto dei FOLDS.
 *
 * RESTITUISCE: Un puntatore alla linea cercata.
 *
 ****/

struct Line *SearchLine(struct Line *line,int y)
{
	while(((y--)>0)&&(line))	line=NextLine(line);
	return(line);
}



/*****
 *
 * FUNZIONE:	int SearchLine2(struct Line *line,int y)
 *
 * SCOPO:	Cerca il # della linea (tenendo conto dei FOLD)
 *		della linea ASSOLUTA y.
 *
 * RESTITUISCE: Il # della linea cercata.
 *
 ****/

int SearchLine2(struct Line *line,int y)
{
	int	n=0;

	while(((y--)>0)&&(line))
	{
		if (!line->Folder)	n++;
		else	if (line->NextLine)
				if (!line->NextLine->Folder)	n++;
		line=line->NextLine;
	}
	if (line)	return(n);
	else		return(0);
}



/*****
 *
 * FUNZIONE:	int SearchLine3(struct Line *first,struct Line *line)
 *
 * SCOPO:	Cerca il # assoluto della linea line a partire
 *		dalla prima linea del file data da first.
 *		NB: NON tiene conto dei FOLDS.
 *
 * RESTITUISCE: Il # della linea cercata.
 *
 ****/

int SearchLine3(struct Line *first,struct Line *line)
{
	long	n=0;

	while(first)
	{
		if (first==line)	break;
		n++;
		first=first->NextLine;
	}
	return(n);
}



/*****
 *
 * FUNZIONE:	struct Line *SearchLine4(struct Line *line,int y)
 *
 * SCOPO:	Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
 *		dalla prima linea del file data da line.
 *		NB: NON tiene conto dei FOLDS.
 *
 * RESTITUISCE: Un puntatore alla linea cercata.
 *
 ****/

struct Line *SearchLine4(struct Line *line,int y)
{
	while(((y--)>0)&&(line))	line=line->NextLine;
	return(line);
}