home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga Shareware Floppies / ma76.lha / MAShare76 / proged.lha / proged22 / installproged / sources / DevManual_GER < prev    next >
Encoding:
Text File  |  1996-07-22  |  13.4 KB  |  465 lines
  1.  
  2.               -----------------------------------------------
  3.  
  4.                 ProgED V2.x by Giovanni Lambiase (C) 1995-96
  5.  
  6.                              Entwickleranmerkungen
  7.  
  8.               -----------------------------------------------
  9.  
  10.  
  11. --------------------
  12.  1. Hauptstrukturen
  13. --------------------
  14.  
  15.     Wenn Sie etwas über Strukturen wissen möchten, finden Sie mehr
  16.     darüber in der Datei PED.h.
  17.  
  18.  
  19.  
  20. ------------
  21.  2. Scanner
  22. ------------
  23.  
  24.     Ein Scanner muß so geschrieben sein, daß sie eine ASM- oder eine
  25. C-Funktion verwendet. Wenn Sie eine C-Funktion verwenden, MÜSSEN Sie
  26. die __asm, __saveds & register __XX - Direktiven des SAS/C verwenden.
  27. Außerdem dürfen Sie KEINE Startup-Module verwenden. Die erste Stelle
  28. muß die Startstelle der Funktion sein. Die Suchfunktion erhält zwei
  29. Argumente im A0- und A1-Register:
  30.  
  31.     A0: Adresse des Zeilenpuffers. Es zeigt auf einen 0-terminierten
  32.         String.
  33.  
  34.     A1: Adresse des Namenspuffers.
  35.  
  36.     Die Funktion MUSS in D0 die Länge des Strings, der in dem durch
  37. A1 indizierten Puffer abgelegt wurde, zurückliefern. Wenn die Funktion
  38. fehlschlug, muß eine 0 zurückgeliefert werden.
  39.  
  40.     ANMERKUNG: Sie MÜSSEN alle Register beim Einstieg auf den Stack
  41.         retten und beim Beenden zurückholen.
  42.  
  43.  
  44.  
  45. --------------
  46.  3. Faltungen
  47. --------------
  48.  
  49.     Sie können mit den gleichen Regeln wie in Scanner Faltungen erstellen:
  50.  
  51.       1) Verwenden Sie eine C- oder ASM-Funktion
  52.       2) Verwenden Sie __asm, __saveds & register __XX-Direktiven
  53.       3) Verwenden Sie keine Startup-Module
  54.       4) Erste Stelle muß der Funktionsstart sein.
  55.       5) Sie müssen alle Register auf dem Stack retten und am Ende
  56.          restaurieren.
  57.  
  58.     Ein Falter erhält Argumenten in den folgenden Registern:
  59.  
  60.     A0: Adresse der PEDWindow-Struktur. Sie müssen an dem Text in diesem
  61.         Fenster arbeiten.
  62.  
  63.     D0: Cursor-Spaltennummer (0=erste Spalte).
  64.  
  65.     D1: Cursor-Zeilennummer (0=erste Zeile). Dieser Wert ist ABSOLUT. Das
  66.         bedeutet das dies eine ECHTE Zeilennummer vom Textstart an gemessen
  67.         ist.
  68.  
  69.     A1: Adresse eines Langwortes. An dieser Adresse MUSS die Funktion
  70.         die Startzeilennummer der Faltung als Langwort schreiben, wenn
  71.         eine gefunden wurde. Um diesen Wert zu berechnen, muß die Funktion
  72.         die ABSOLUTE Zeilennummer ermitteln (0=erste Zeile).
  73.  
  74.     A2: Adresse eines Langwortes. An dieser Adresse MUSS die Funktion
  75.         die Endzeilennummer der Faltung als Langwort schreiben, wenn
  76.         eine gefunden wurde. Um diesen Wert zu berechnen, muß die Funktion
  77.         die ABSOLUTE Zeilennummer ermitteln (0=erste Zeile).
  78.  
  79.     A3: Zeigt auf einen Puffer. Wenn Ihre Funktion eine Faltung gefunden
  80.         hat, muß sie in diesen Puffer den Namen der Faltung eintragen.
  81.         ProgED zeigt ihn an. Normalerweise schreiben Sie hier den Namen
  82.         der gefundenen Funktion hinein.
  83.  
  84.     Die Scannerfunktion MUSS in D0 eine 1 zurückliefern, wenn eine Faltung
  85. gefunden wurde, ansonsten 0. Wenn eine Faltung gefunden wurde, muß Ihre
  86. Funktion die Start- und Endzeilennummern in den Langworten, die von A1
  87. und A2 indiziert wurden, und den Funktionsnamen in dem Puffer, auf den A3
  88. zeigt, zurückliefern.
  89.  
  90.     ANMERKUNG: Die 'FOLD ALL'-Funktion wird ausgeführt, indem Ihre Funk-
  91. tion an ALLEN Zeilen des Textes aufgerufen wird. Bei jedem Aufruf steht
  92. der Cursor auf der ersten Spalte (D1 enthält 0).
  93.  
  94.  
  95.  
  96. -----------------
  97.  4. API-Klienten
  98. -----------------
  99.  
  100.     ProgED erlaubt es Ihnen, externe Applikationen ("Klienten" genannt)
  101. einzuklinken. Ein API-Klient ist einfach ein ausführbares Programm (in
  102. jeder beliebigen Sprache geschrieben). Dieses Programm muß sich selbst
  103. am ProgED API-Port eintragen. So kann ProgED seine Klienten abtasten
  104. und ihnen einige Informationen darüber schicken, was sie zu tun haben.
  105. Die Messages, die ein Klient an ProgED senden kann (an den API-Port,
  106. genannt "PED_API"), hat die folgende Struktur:
  107.  
  108.     struct APIMessage
  109.     {
  110.         struct Message     am_Message;
  111.         ULONG              am_MsgType,
  112.                            am_MsgArg[10],
  113.                            am_RC;
  114.     }
  115.  
  116.     am_Message:
  117.  
  118.         Standard exec-Message
  119.  
  120.     am_MsgType:
  121.  
  122.         Typ der Message
  123.  
  124.     am_MsgArg[]:
  125.  
  126.         Argument-Array der Message
  127.  
  128.     am_RC:
  129.  
  130.         Returncode
  131.  
  132.  
  133.  
  134.  
  135.     Ein Klient kann folgende Nachrichten an ProgED senden:
  136.  
  137.     PED_API_REGISTER:
  138.  
  139.         "Trag mich ein". In am_MsgArg[0] müssen Sie einen Zeiger auf
  140.         die APIClient-Struktur liefern. Diese Nachricht liefert nichts
  141.         zurück.
  142.  
  143.     PED_API_UNREGISTER:
  144.  
  145.         "Trag mich aus". Diese Nachricht muß verwendet werden, wenn der
  146.         Klient weggehen möchte (!?!). In am_MsgArg[0] muß der Pointer
  147.         übergeben werden, den Sie in PED_API_REGISTER verwendet haben.
  148.         Auch diese Funktion liefert nichts zurück.
  149.  
  150.     PED_API_ADD_INTERNAL_COMMAND:
  151.  
  152.         Ein Klient kann neue interne Kommandos hinzufügen. Sie müssen
  153.         eine ArexxExtCmds-Struktur erstellen und seine Adresse in
  154.         am_MsgArg[0] übergeben. Diese Funktion liefert nichts zurück.
  155.  
  156.     PED_API_REM_INTERNAL_COMMAND:
  157.  
  158.         Wenn Sie ein vorher eingefügtes internes Kommando entfernen
  159.         möchten, müssen Sie diese Nachricht verwenden. Schreiben Sie
  160.         die Adresse Ihrer ArexxExtCmds-Struktur in am_MsgArg[0]. Diese
  161.         Funktion liefert nichts zurück.
  162.  
  163.     PED_API_GET_ACTIVE_WINDOW:
  164.  
  165.         Holt die Adresse der momentan aktiven PEDWindow-Struktur.
  166.         Sie finden die Adresse in am_RC.
  167.  
  168.     PED_API_GET_WINDOW_LIST:
  169.  
  170.         Holt den Zeiger auf die erste PEDWindow-Struktur in der ProgED-
  171.         Liste. Sie finden die Adresse in am_RC.
  172.  
  173.     PED_GET_SCREEN_ADDRESS:
  174.  
  175.         Holt die ProgED-Screenadresse. Wenn ProgED momentan ikonifiziert
  176.         ist, wird NULL zurückgeliefert. Sie finden die Adresse in am_RC.
  177.  
  178.     PED_GET_PREFS_ADDRESS:
  179.  
  180.         Holt die Adresse der Prefs-Struktur in am_RC.
  181.  
  182.     PED_GET_PUBSCRNAME:
  183.  
  184.         Holt den ProgED-Publicscreen-Name in am_RC.
  185.  
  186.     ANMERKUNG: Die ArexxExtCmds-Struktur MUSS solange gültig bleiben,
  187.         bis Sie das PED_API_REM_INTERNAL_COMMAND beantwortet haben. Danach
  188.         können Sie sie freigeben oder recyclen.
  189.  
  190.  
  191.  
  192.     ProgED kann einem Klienten folgende Nachrichten schicken:
  193.  
  194.     PED_API_SHOW:
  195.  
  196.           "Ich habe meinen Screen geöffnet. Meine Screen-Adresse ist in
  197.           am_MsgArg[0]. Der PubScreen-Name steht in am_MsgArg[1]". Dadurch
  198.           können Sie Ihre Fenster auf dem ProgED-Schirm öffnen. Sie er-
  199.           halten diese Nachricht NUR DANN, wenn Sie NOTIFY_ON_SHOWHIDE
  200.           im Flagfeld der APIClients-Struktur angegeben haben.
  201.  
  202.     PED_API_HIDE:
  203.  
  204.           "Ich schließe meinen Screen!". Sie erhalten diese Nachricht wenn
  205.           ProgED dabei ist, seinen Schirm zu schließen. Schließen Sie ALLE
  206.           Ihre Fenster. Sie erhalten diese Nachricht NUR DANN, wenn Sie
  207.           NOTIFY_ON_SHOWHIDE im Flagfeld der APIClients-Struktur angegeben
  208.           haben.
  209.  
  210.     PED_API_KEY:
  211.  
  212.           "Benutzer drückte eine Taste!". Der Klient kann die zugehörige
  213.           IntuiMessage-Struktur in am_MsgArg[0] lesen. Dieses Feld ent-
  214.           hält die Adresse auf eine IntuiMessage-Struktur, die eine RAWKEY
  215.           Message angibt. In am_MsgArg[1] bekommt der Klient einen Zeiger
  216.           auf die PEDWindow-Struktur, die die RAWKEY-Nachricht erhalten hat.
  217.           Sie erhalten die Nachricht NUR DANN, wenn Sie NOTIFY_ON_KEY in
  218.           dem Flagfeld der APIClients-Struktur angegeben haben.
  219.  
  220.           ANMERKUNG: Wenn Sie diese Nachricht beantworten, wird ProgED die
  221.                 an die Taste angebundene Aktion ausführen. Sie können die
  222.                 IntuiMessage auch nicht modifizieren. Es ist eine
  223.                 Intuition-Nachricht! (:-o
  224.  
  225.     PED_API_QUIT:
  226.  
  227.           "Ich beende mich!" Wenn Ihr Klient diese Nachricht empfängt,
  228.           MÜSSEN Sie alle Fenster schließen UND sich BEENDEN. Sie dürfen
  229.           den API-Port nach dieser Nachricht NICHT MEHR verwenden! Ihr
  230.           Klient sollte nicht versuchen, Kommandos und die Registration
  231.           zu entfernen. SIE MÜSSEN SICH EINFACH NUR BEENDEN!
  232.  
  233.  
  234.  
  235.     Hier finden Sie ein paar Informationen über die APIClient-Struktur.
  236.  
  237.  
  238.     struct APIClient
  239.     {
  240.         struct MsgPort          *ac_ClientPort;
  241.         ULONG                    ac_Notify;
  242.         char                    *ac_name;
  243.         struct APIClient        *ac_Next;
  244.     }
  245.  
  246.     ac_ClientPort:
  247.  
  248.         Adresse des MessagePorts des Klienten. Sie müssen hier einen
  249.         MessagePort angeben. ProgED sendet die Nachrichten auf diesem
  250.         Port zu Ihnen.
  251.  
  252.     ac_Notify:
  253.  
  254.         Wenn Sie NOTIFY_ON_SHOW_HIDE angeben, erhalten Sie die
  255.         PED_API_SHOW und PED_API_HIDE-Nachrichten. Mit NOTIFY_ON_KEY
  256.         erhalten Sie einige Informationen über Tastendrücke durch
  257.         PED_API_KEY-Nachrichten.
  258.  
  259.     ac_Name:
  260.  
  261.         Name des Klienten.
  262.  
  263.     ac_Next:
  264.  
  265.         Auf NULL setzen. Es wird nachher mit der Adresse des nächsten
  266.         Klienten ausgefüllt.
  267.  
  268.  
  269.  
  270.  
  271.     struct ArexxExtCmds
  272.     {
  273.         UBYTE                    External;
  274.         char                    *Name;
  275.         char                    *Template;
  276.         void                    *Defaults[MAXREXXARGS];
  277.         LONG ASM                (*CommFunc)( RG(a0) struct CommandData *);
  278.         struct ArexxExtCmds     *NextCmd;
  279.     }
  280.  
  281.     External:
  282.  
  283.         Setzen Sie es auf TRUE. Das bedeutet, es ist ein "externes" Kommando.
  284.  
  285.     Name:
  286.  
  287.         Kommandoname. Write it using case letters.
  288.  
  289.     Template:
  290.  
  291.         ReadArgs-Muster.
  292.  
  293.     Default[]:
  294.  
  295.         Array mit Defaultwerten für die Argumente.
  296.  
  297.     CommFunc:
  298.  
  299.         Adresse der Funktion zu diesem Kommando. Diese Funktion muß
  300.         in ASM oder mit __asm und __saveds-Direktiven geschrieben
  301.         sein. Sie erhält eine CommandData-Struktur im A0-Register.
  302.         Diese Funktion muß im D0-Register einen Error-Code zurücklie-
  303.         fern (siehe RC_xxx).
  304.  
  305.     NextCmd:
  306.  
  307.         Immer auf NULL setzen.
  308.  
  309.  
  310.  
  311.  
  312.     struct CommandData
  313.     {
  314.         char              *CommandLine;
  315.         void             **CommandArgs;
  316.         struct MyWindow   *CurrentWindow,
  317.                           *FirstWindow;
  318.         struct Prefs      *CurrentPrefs;
  319.         LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
  320.     }
  321.  
  322.     CommandLine:
  323.  
  324.         Dieses Feld zeigt auf einen String, der die ganze Kommandozeile
  325.         enthält. Verwenden Sie ihn wie Sie möchten.
  326.  
  327.     CommandArgs:
  328.  
  329.         Zeigt auf ein Array von void *. Dieses Array ist das Ergebnis
  330.         der ReadArgs-Funktion auf den Kommandostring. Siehe ReadArgs,
  331.         wie Sie die Pointer verwenden.
  332.  
  333.     CurrentWindow:
  334.  
  335.         Zeigt auf das aktive PEDWindow.
  336.  
  337.     FirstWindow:
  338.  
  339.         Zeigt auf das erste PEDWindow.
  340.  
  341.     CurrentPrefs:
  342.  
  343.         Zeigt auf die Prefs-Struktur mit den aktuellen Voreinstellungen.
  344.  
  345.     ExecuteInternalCommand:
  346.  
  347.         Dies ist ein Zeiger auf eine Assemblerfunktion. Sie können
  348.         diese Funktion aufrufen, um ein ProgED-internes Kommando aus-
  349.         zuführen. Um dies zu machen, schreiben Sie ins A0-Register
  350.         einen Zeiger auf den Kommandostring, der ausgeführt werden
  351.         soll. Im D0-Register erhalten Sie einen Returncode (RC_xxx).
  352.  
  353.         ANMERKUNG: Verwenden Sie nicht den ProgED-ARexx-Port, um ein
  354.         internes Kommando auszuführen! Dadurch würde sich ProgED und
  355.         der Klient aufhängen!
  356.  
  357.  
  358.  
  359. -----------------------
  360.  5. Utility-Funktionen
  361. -----------------------
  362.  
  363.     Die folgenden C-Funktionen sind nützlich, wenn Sie Ihre eigenen
  364. Falter und Scanner schreiben möchten. Sie können sie ausschneiden und
  365. in Ihren eigenen Funktionen verwenden. Diese Funktionen suchen nach
  366. Zeilen im ProgED-Text.
  367.  
  368.  
  369.  
  370. /*****
  371.  *
  372.  * FUNKTION:    struct Line *SearchLine(struct Line *line,int y)
  373.  *
  374.  * ZIEL:        Sucht die y. Zeile (ohne über Falten zu springen),
  375.  *              beginnend von der ersten Zeile im Text, die in "line"
  376.  *              angegeben wurde.
  377.  *
  378.  * ERGEBNIS:    Ein Zeiger auf die gesuchte Zeile
  379.  *
  380.  ****/
  381.  
  382. struct Line *SearchLine(struct Line *line,int y)
  383. {
  384.         while(((y--)>0)&&(line))        line=NextLine(line);
  385.         return(line);
  386. }
  387.  
  388.  
  389.  
  390. /*****
  391.  *
  392.  * FUNKTION:    int SearchLine2(struct Line *line,int y)
  393.  *
  394.  * ZIEL:        Sucht nach der Zeilennummer (springt über Faltungen)
  395.  *              der Zeile mit der Nummer "y" (ohne Faltungen).
  396.  *
  397.  * ERGEBNIS:    Nummer der gesuchten Zeile
  398.  *
  399.  ****/
  400.  
  401. int SearchLine2(struct Line *line,int y)
  402. {
  403.         int     n=0;
  404.  
  405.         while(((y--)>0)&&(line))
  406.         {
  407.                 if (!line->Folder)      n++;
  408.                 else    if (line->NextLine)
  409.                                 if (!line->NextLine->Folder)    n++;
  410.                 line=line->NextLine;
  411.         }
  412.         if (line)       return(n);
  413.         else            return(0);
  414. }
  415.  
  416.  
  417.  
  418. /*****
  419.  *
  420.  * FUNKTION:    int SearchLine3(struct Line *first,struct Line *line)
  421.  *
  422.  * ZIEL:        Sucht nach der Zeilennummer (ohne über Falten zu springen)
  423.  *              der Zeile, die mit "line" angegeben wurde. "first" zeigt
  424.  *              auf die erste Zeile im Text.
  425.  *
  426.  * ERGEBNIS:    Nr. der gesuchten Zeile
  427.  *
  428.  ****/
  429.  
  430. int SearchLine3(struct Line *first,struct Line *line)
  431. {
  432.         long    n=0;
  433.  
  434.         while(first)
  435.         {
  436.                 if (first==line)        break;
  437.                 n++;
  438.                 first=first->NextLine;
  439.         }
  440.         return(n);
  441. }
  442.  
  443.  
  444.  
  445. /*****
  446.  *
  447.  * FUNKTION:    struct Line *SearchLine4(struct Line *line,int y)
  448.  *
  449.  * ZIEL:        Sucht nach der Adresse der Zeile Nummer y. "line"
  450.  *              zeigt auf die erste Zeile des Textes. Das Ergebnis
  451.  *              der Funktion ist ABSOLUT (springt nicht über Falten).
  452.  *
  453.  * ERGEBNIS:    Ein Zeiger auf die gesuchte Zeile
  454.  *
  455.  ****/
  456.  
  457. struct Line *SearchLine4(struct Line *line,int y)
  458. {
  459.         while(((y--)>0)&&(line))        line=line->NextLine;
  460.         return(line);
  461. }
  462.  
  463.  
  464.  
  465.