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

                ProgED V2.x by Giovanni Lambiase (C) 1995-97

                             Entwickleranmerkungen

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


--------------------
 1. Hauptstrukturen
--------------------

    Wenn Sie etwas ber Strukturen wissen mchten, finden Sie mehr
    darber in der Datei PED.h.



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

    Ein Scanner mu so geschrieben sein, da sie eine ASM- oder eine
C-Funktion verwendet. Wenn Sie eine C-Funktion verwenden, MSSEN Sie
die __asm, __saveds & register __XX - Direktiven des SAS/C verwenden.
Auerdem drfen Sie KEINE Startup-Module verwenden. Die erste Stelle
mu die Startstelle der Funktion sein. Die Suchfunktion erhlt zwei
Argumente im A0- und A1-Register:

    A0: Adresse des Zeilenpuffers. Es zeigt auf einen 0-terminierten
        String.

    A1: Adresse des Namenspuffers.

    Die Funktion MUSS in D0 die Lnge des Strings, der in dem durch
A1 indizierten Puffer abgelegt wurde, zurckliefern. Wenn die Funktion
fehlschlug, mu eine 0 zurckgeliefert werden.

    ANMERKUNG: Sie MSSEN alle Register beim Einstieg auf den Stack
        retten und beim Beenden zurckholen.



--------------
 3. Faltungen
--------------

    Sie knnen mit den gleichen Regeln wie in Scanner Faltungen erstellen:

      1) Verwenden Sie eine C- oder ASM-Funktion
      2) Verwenden Sie __asm, __saveds & register __XX-Direktiven
      3) Verwenden Sie keine Startup-Module
      4) Erste Stelle mu der Funktionsstart sein.
      5) Sie mssen alle Register auf dem Stack retten und am Ende
         restaurieren.

    Ein Falter erhlt Argumenten in den folgenden Registern:

    A0: Adresse der PEDWindow-Struktur. Sie mssen an dem Text in diesem
        Fenster arbeiten.

    D0: Cursor-Spaltennummer (0=erste Spalte).

    D1: Cursor-Zeilennummer (0=erste Zeile). Dieser Wert ist ABSOLUT. Das
        bedeutet das dies eine ECHTE Zeilennummer vom Textstart an gemessen
        ist.

    A1: Adresse eines Langwortes. An dieser Adresse MUSS die Funktion
        die Startzeilennummer der Faltung als Langwort schreiben, wenn
        eine gefunden wurde. Um diesen Wert zu berechnen, mu die Funktion
        die ABSOLUTE Zeilennummer ermitteln (0=erste Zeile).

    A2: Adresse eines Langwortes. An dieser Adresse MUSS die Funktion
        die Endzeilennummer der Faltung als Langwort schreiben, wenn
        eine gefunden wurde. Um diesen Wert zu berechnen, mu die Funktion
        die ABSOLUTE Zeilennummer ermitteln (0=erste Zeile).

    A3: Zeigt auf einen Puffer. Wenn Ihre Funktion eine Faltung gefunden
        hat, mu sie in diesen Puffer den Namen der Faltung eintragen.
        ProgED zeigt ihn an. Normalerweise schreiben Sie hier den Namen
        der gefundenen Funktion hinein.

    Die Scannerfunktion MUSS in D0 eine 1 zurckliefern, wenn eine Faltung
gefunden wurde, ansonsten 0. Wenn eine Faltung gefunden wurde, mu Ihre
Funktion die Start- und Endzeilennummern in den Langworten, die von A1
und A2 indiziert wurden, und den Funktionsnamen in dem Puffer, auf den A3
zeigt, zurckliefern.

    ANMERKUNG: Die 'FOLD ALL'-Funktion wird ausgefhrt, indem Ihre Funk-
tion an ALLEN Zeilen des Textes aufgerufen wird. Bei jedem Aufruf steht
der Cursor auf der ersten Spalte (D1 enthlt 0).



-----------------
 4. API-Klienten
-----------------

    ProgED erlaubt es Ihnen, externe Applikationen ("Klienten" genannt)
einzuklinken. Ein API-Klient ist einfach ein ausfhrbares Programm (in
jeder beliebigen Sprache geschrieben). Dieses Programm mu sich selbst
am ProgED API-Port eintragen. So kann ProgED seine Klienten abtasten
und ihnen einige Informationen darber schicken, was sie zu tun haben.
Die Messages, die ein Klient an ProgED senden kann (an den API-Port,
genannt "PED_API"), hat die folgende Struktur:

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

    am_Message:

        Standard exec-Message

    am_MsgType:

        Typ der Message

    am_MsgArg[]:

        Argument-Array der Message

    am_RC:

        Returncode




    Ein Klient kann folgende Nachrichten an ProgED senden:

    PED_API_REGISTER:

        "Trag mich ein". In am_MsgArg[0] mssen Sie einen Zeiger auf
        die APIClient-Struktur liefern. Diese Nachricht liefert nichts
        zurck.

    PED_API_UNREGISTER:

        "Trag mich aus". Diese Nachricht mu verwendet werden, wenn der
        Klient weggehen mchte (!?!). In am_MsgArg[0] mu der Pointer
        bergeben werden, den Sie in PED_API_REGISTER verwendet haben.
        Auch diese Funktion liefert nichts zurck.

    PED_API_ADD_INTERNAL_COMMAND:

        Ein Klient kann neue interne Kommandos hinzufgen. Sie mssen
        eine ArexxExtCmds-Struktur erstellen und seine Adresse in
        am_MsgArg[0] bergeben. Diese Funktion liefert nichts zurck.

    PED_API_REM_INTERNAL_COMMAND:

        Wenn Sie ein vorher eingefgtes internes Kommando entfernen
        mchten, mssen Sie diese Nachricht verwenden. Schreiben Sie
        die Adresse Ihrer ArexxExtCmds-Struktur in am_MsgArg[0]. Diese
        Funktion liefert nichts zurck.

    PED_API_GET_ACTIVE_WINDOW:

        Holt die Adresse der momentan aktiven PEDWindow-Struktur.
        Sie finden die Adresse in am_RC.

    PED_API_GET_WINDOW_LIST:

        Holt den Zeiger auf die erste PEDWindow-Struktur in der ProgED-
        Liste. Sie finden die Adresse in am_RC.

    PED_API_GET_SCREEN_ADDRESS:

        Holt die ProgED-Screenadresse. Wenn ProgED momentan ikonifiziert
        ist, wird NULL zurckgeliefert. Sie finden die Adresse in am_RC.

    PED_API_GET_PREFS_ADDRESS:

        Holt die Adresse der Prefs-Struktur in am_RC.

    PED_API_GET_PUBSCRNAME:

        Holt den ProgED-Publicscreen-Name in am_RC.

    ANMERKUNG: Die ArexxExtCmds-Struktur MUSS solange gltig bleiben,
        bis Sie das PED_API_REM_INTERNAL_COMMAND beantwortet haben. Danach
        knnen Sie sie freigeben oder recyclen.



    ProgED kann einem Klienten folgende Nachrichten schicken:

    PED_API_SHOW:

          "Ich habe meinen Screen geffnet. Meine Screen-Adresse ist in
          am_MsgArg[0]. Der PubScreen-Name steht in am_MsgArg[1]". Dadurch
          knnen Sie Ihre Fenster auf dem ProgED-Schirm ffnen. Sie er-
          halten diese Nachricht NUR DANN, wenn Sie NOTIFY_ON_SHOWHIDE
          im Flagfeld der APIClients-Struktur angegeben haben.

    PED_API_HIDE:

          "Ich schliee meinen Screen!". Sie erhalten diese Nachricht wenn
          ProgED dabei ist, seinen Schirm zu schlieen. Schlieen Sie ALLE
          Ihre Fenster. Sie erhalten diese Nachricht NUR DANN, wenn Sie
          NOTIFY_ON_SHOWHIDE im Flagfeld der APIClients-Struktur angegeben
          haben.

    PED_API_KEY:

          "Benutzer drckte eine Taste!". Der Klient kann die zugehrige
          IntuiMessage-Struktur in am_MsgArg[0] lesen. Dieses Feld ent-
          hlt die Adresse auf eine IntuiMessage-Struktur, die eine RAWKEY
          Message angibt. In am_MsgArg[1] bekommt der Klient einen Zeiger
          auf die PEDWindow-Struktur, die die RAWKEY-Nachricht erhalten hat.
          Sie erhalten die Nachricht NUR DANN, wenn Sie NOTIFY_ON_KEY in
          dem Flagfeld der APIClients-Struktur angegeben haben.

          ANMERKUNG: Wenn Sie diese Nachricht beantworten, wird ProgED die
                an die Taste angebundene Aktion ausfhren. Sie knnen die
                IntuiMessage auch nicht modifizieren. Es ist eine
                Intuition-Nachricht! (:-o

    PED_API_QUIT:

          "Ich beende mich!" Wenn Ihr Klient diese Nachricht empfngt,
          MSSEN Sie alle Fenster schlieen UND sich BEENDEN. Sie drfen
          den API-Port nach dieser Nachricht NICHT MEHR verwenden! Ihr
          Klient sollte nicht versuchen, Kommandos und die Registration
          zu entfernen. SIE MSSEN SICH EINFACH NUR BEENDEN!



    Hier finden Sie ein paar Informationen ber die APIClient-Struktur.


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

    ac_ClientPort:

        Adresse des MessagePorts des Klienten. Sie mssen hier einen
        MessagePort angeben. ProgED sendet die Nachrichten auf diesem
        Port zu Ihnen.

    ac_Notify:

        Wenn Sie NOTIFY_ON_SHOW_HIDE angeben, erhalten Sie die
        PED_API_SHOW und PED_API_HIDE-Nachrichten. Mit NOTIFY_ON_KEY
        erhalten Sie einige Informationen ber Tastendrcke durch
        PED_API_KEY-Nachrichten.

    ac_Name:

        Name des Klienten.

    ac_Next:

        Auf NULL setzen. Es wird nachher mit der Adresse des nchsten
        Klienten ausgefllt.




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

    External:

        Setzen Sie es auf TRUE. Das bedeutet, es ist ein "externes" Kommando.

    Name:

        Kommandoname. Write it using case letters.

    Template:

        ReadArgs-Muster.

    Default[]:

        Array mit Defaultwerten fr die Argumente.

    CommFunc:

        Adresse der Funktion zu diesem Kommando. Diese Funktion mu
        in ASM oder mit __asm und __saveds-Direktiven geschrieben
        sein. Sie erhlt eine CommandData-Struktur im A0-Register.
        Diese Funktion mu im D0-Register einen Error-Code zurcklie-
        fern (siehe RC_xxx).

    NextCmd:

        Immer auf NULL setzen.




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

    CommandLine:

        Dieses Feld zeigt auf einen String, der die ganze Kommandozeile
        enthlt. Verwenden Sie ihn wie Sie mchten.

    CommandArgs:

        Zeigt auf ein Array von void *. Dieses Array ist das Ergebnis
        der ReadArgs-Funktion auf den Kommandostring. Siehe ReadArgs,
        wie Sie die Pointer verwenden.

    CurrentWindow:

        Zeigt auf das aktive PEDWindow.

    FirstWindow:

        Zeigt auf das erste PEDWindow.

    CurrentPrefs:

        Zeigt auf die Prefs-Struktur mit den aktuellen Voreinstellungen.

    ExecuteInternalCommand:

        Dies ist ein Zeiger auf eine Assemblerfunktion. Sie knnen
        diese Funktion aufrufen, um ein ProgED-internes Kommando aus-
        zufhren. Um dies zu machen, schreiben Sie ins A0-Register
        einen Zeiger auf den Kommandostring, der ausgefhrt werden
        soll. Im D0-Register erhalten Sie einen Returncode (RC_xxx).

        ANMERKUNG: Verwenden Sie nicht den ProgED-ARexx-Port, um ein
        internes Kommando auszufhren! Dadurch wrde sich ProgED und
        der Klient aufhngen!



-----------------------
 5. Utility-Funktionen
-----------------------

    Die folgenden C-Funktionen sind ntzlich, wenn Sie Ihre eigenen
Falter und Scanner schreiben mchten. Sie knnen sie ausschneiden und
in Ihren eigenen Funktionen verwenden. Diese Funktionen suchen nach
Zeilen im ProgED-Text.



/*****
 *
 * FUNKTION:    struct Line *SearchLine(struct Line *line,int y)
 *
 * ZIEL:        Sucht die y. Zeile (ohne ber Falten zu springen),
 *              beginnend von der ersten Zeile im Text, die in "line"
 *              angegeben wurde.
 *
 * ERGEBNIS:    Ein Zeiger auf die gesuchte Zeile
 *
 ****/

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



/*****
 *
 * FUNKTION:    int SearchLine2(struct Line *line,int y)
 *
 * ZIEL:        Sucht nach der Zeilennummer (springt ber Faltungen)
 *              der Zeile mit der Nummer "y" (ohne Faltungen).
 *
 * ERGEBNIS:    Nummer der gesuchten Zeile
 *
 ****/

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);
}



/*****
 *
 * FUNKTION:    int SearchLine3(struct Line *first,struct Line *line)
 *
 * ZIEL:        Sucht nach der Zeilennummer (ohne ber Falten zu springen)
 *              der Zeile, die mit "line" angegeben wurde. "first" zeigt
 *              auf die erste Zeile im Text.
 *
 * ERGEBNIS:    Nr. der gesuchten Zeile
 *
 ****/

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

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



/*****
 *
 * FUNKTION:    struct Line *SearchLine4(struct Line *line,int y)
 *
 * ZIEL:        Sucht nach der Adresse der Zeile Nummer y. "line"
 *              zeigt auf die erste Zeile des Textes. Das Ergebnis
 *              der Funktion ist ABSOLUT (springt nicht ber Falten).
 *
 * ERGEBNIS:    Ein Zeiger auf die gesuchte Zeile
 *
 ****/

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



