ATOS - Around The Operating System Das ATOS-Magazin 6/96

# OLGA

OLGA - Object Linking for GEM Applications

Teil 3: ID4-OLGA - InplaceDrawing

Übersicht:
Welche Dateien sind ID4-tauglich?
Objekte einbinden
Objekte zeichnen
Objekte freigeben
Ausblick
Bezugsquelle

Nachdem das bisher vorgestellte OLGA-Protokoll immer mehr Verbreitung findet (man denke nur an die Kombinationen qed+CAB oder ArtWorx+STELLA bzw. ArtWorx+Papillon), ist es wieder mal an der Zeit, einen Blick über den Tellerrand zu werfen. Diverse andere Systeme sind nämlich derzeit dabei, den Schritt von den "Compound Documents" (zusammengesetzte Dokumente, das entspricht ungefähr dem bisherigen OLGA) hin zur "Component Software" zu vollziehen, die die Teile eines Dokuments als jeweils eigenständige Komponenten ansieht. Was heißt das nun für den Anwender?

Bisher wird OLGA folgendermaßen eingesetzt: Wenn ein in CAB geladenes HTML-Dokument in qed verändert und gespeichert wird, bekommt CAB dies durch den OLGA-Manager mit und zeigt das geänderte Dokument in seinem Fenster neu an. Das funktioniert ebenso mit Textobjekten in Texel, die Texel selbst in einem seiner Fenster darstellt. Problematisch wird es allerdings mit Diagrammen (oder ähnlichen Grafiken), denn für diese besitzt Texel keine eigenen Darstellungsroutinen. Genau hierfür wurde die ID4-OLGA-Erweiterung ("InplaceDrawing for OLGA") geschaffen. Texel bittet nun ArtWorx (mit Hilfe des OLGA-Managers), eine Diagrammdatei zu laden und darzustellen, weist diesem Diagramm einen (rechteckigen) Ausgabebereich in einem Texel-Rechenfenster zu und läßt dann ArtWorx das Diagramm innerhalb des Texel-Fensters zeichnen. Das könnte dann beispielsweise so aussehen:

Das funktioniert natürlich nicht nur mit der Bildschirmanzeige, sondern auch mit der Druckerausgabe, genauer: Mit allen GDOS-Geräten. Der Vorteil für den Anwender ist, daß er ID4-Clients (sogenannte "Containerapplikationen") mit der Funktionalität von ID4-Servern erweitern kann, ohne daß diese Server bei der Programmierung des Clients vorhanden oder bekannt sein müssen.

Dieser Artikel beschreibt ID4-OLGA nach der Definition vom 20.11.96. Zu diesem Zeitpunkt unterstützen ArtWorx (ID4-Server, ab Version 1.14) und Texel (ID4-Client, ab Version 1.50) InplaceDrawing. Außerdem ist ein OLGA-Manager ab Version 1.20 nötig. Die folgenden Ausführungen sind nicht nur für Programmierer interessant, da ich auf die genaue Beschreibung der Messages etc. verzichte, sondern nur die entsprechenden Stichworte zur Suche in der OLGA-Dokumentation liefere. Diese sollte passend zu diesem Artikel in den Mailboxen zu finden sein.

### Welche Dateien sind ID4-tauglich?

Damit ein ID4-Client ein ID4-Objekt einbinden kann (wobei es prinzipiell erst einmal egal ist, ob dies durch Linking oder durch Embedding geschieht - siehe ATOS 2/96), muß er alle vorhandenen ID4-Server kennen. Dazu muß der Anwender einmalig beim Installieren eines ID4-Server die Datei OLGA.INF anpassen (falls dies nicht der Installer übernimmt):

      [Objects]
      .CWG=ArtWorx-Dokument
      .CVG=Calamus-Dokument
      .GEM=GEM Metafile
      .AI=Adobe Illustrator-Dokument
      .TAD=Texel-Diagramm

      [Extensions]
      .TAD=$ARTWORX
      .CWG=$ARTWORX
      .CVG=$ARTWORX
      .GEM=$ARTWORX
      .AI=$ARTWORX

Im Abschnitt [Objects] müssen alle Dateitypen samt Klartextbeschreibung eingetragen werden, für die es einen ID4-Server gibt. Das bedeutet für den Server, daß er die ihm zugeordneten Dateien direkt laden können muß (per Kommandozeile oder VA_START). Zu allen in [Objects] eingetragenen Dateitypen muß es auch einen entsprechenden Eintrag in [Extensions] geben.

Der Client fragt die ID4-Dateitypen einzeln beim OLGA-Manager mit der Message OLGA_GETOBJECTS ab, und zwar so lange, bis OLGA_OBJECTS das Ende der Liste signalisiert. Mit letztgenannter Message bekommt der Client nicht nur die Extension, sondern auch die Klartextbeschreibung mitgeteilt, die er dem Benutzer zur Auswahl anbieten kann - beispielsweise mit dem Menüpunkt "Objekt einfügen".

### Objekte einbinden

ID4-Server und -Clients sind zunächst einmal ganz normal angemeldete OLGA-Server und -Clients. Soll ein ID4-Server mit MemoryProtection laufen, so muß das GLOBAL-Flag im Programmheader des Servers gesetzt sein.

Wenn ein Client ein Objekt einbinden möchte, muß er dem OLGA-Manager den Dateityp des gewünschten Objekts mitteilen, damit der Manager den passenden Server nachstarten kann (falls dieser nicht schon läuft). Dazu schickt der Client dem Manager die Message OLGA_ACTIVATE und übergibt die Extension der Datei.

Für jedes einzubindende Objekt legt ein ID4-Client dann folgende OLGAObjectInfo-Struktur im globalen Speicher an:

      GRECTPtr = ^GRECT;
      GRECT    = record
        X,Y,W,H,
        X1,Y1,X2,Y2: integer
      end;

      POLGAObjectInfo = ^TOLGAObjectInfo;
      TOLGAObjectInfo = record
        Filename   : PChar;
        ClientGEMPB: AESPBPtr;
        ClientData,
        ServerData : longint;
        CBLock,
        CBCount    : integer;
        CBDraw     : procedure(d1,d2: pointer; d3,d4,d5: longint;
                               objectinfo: POLGAObjectInfo;
                               outScreen,
                               outHandle,
                               outDevID: integer;
                               Size,
                               Clip: GRECTPtr);
        CBUnembed  : procedure(d1,d2: pointer; d3,d4,d5: longint;
                               objectinfo: POLGAObjectInfo);
      end;

In C-Notation dürfte das in etwa so aussehen:

      typedef struct
      {
        int x,y,w,h,
            x1,y1,x2,y2;
      } GRECT;

      typedef struct ObjectInfo
      {
        char  *Filename;
        AESPB *ClientGEMPB;
        long   ClientData,
               ServerData;
        int    CBLock,
               CBCount;
        void   cdecl (*CBDraw)    (ObjectInfo *objectinfo,
                                   int outScreen,
                                   int outHandle,
                                   int outDevID,
                                   GRECT *Size,
                                   GRECT *Clip);
        void   cdecl (*CBUnembed) (ObjectInfo *objectinfo);
      } OLGAObjectInfo;

Nach der Initialisierung der Struktur (das ist im wesentlichen das Eintragen des Dateinamens sowie das Ausnullen vom Rest) schickt der Client dem Manager die Message OLGA_EMBED mit der OLGAObjectInfo-Struktur als Parameter. Diese Message wird vom Manager an den Server weitergereicht, der daraufhin die Datei laden und auswerten kann. Wenn alles geklappt hat, trägt der Server in der OLGAObjectInfo-Struktur seine Zeichenroutine ein (CBDraw) und schickt dem Client die Antwort OLGA_EMBEDDED, die u.a. die optimale Größe (in 1/100mm) für das Objekt enthält. Erst nachdem der Client OLGA_EMBEDDED empfangen hat, darf er das Objekt schließlich einbinden.

### Objekte zeichnen

Zum Zeichnen eines Objekts ruft ein ID4-Client innerhalb seiner gewöhnlichen WM_REDRAW-Abarbeitung (oder sonst irgend einer Zeichenaufforderung, wichtig ist nur das Durchlaufen der Rechteckliste) für jedes Objekt den CBDraw()-Callback auf, dem die Pixelgröße des Objekts und der aktuelle Clippingbereich übergeben werden.

Wenn der CBDraw()-Callback aufgerufen wird, kann der Server seine normale, leicht angepaßte Zeichenroutine aufrufen, sofern sie mit beliebigen GDOS-Ausgabegeräten zurechtkommt. Während des ID4-Zeichnens (also im CBDraw-Callback) darf der Server kein (!) wind_update() durchführen, da das System sonst verklemmen könnte (der Client sollte ja seinerseits den Bildschirm zur korrekten Ausgabe gesperrt haben). Außerdem darf der Server in dieser Zeit keine AES-Aufrufe machen, falls nicht das AES-global[]-Feld mittels ClientGEMPB aus der OLGAObjectInfo-Struktur angepaßt wurde. Schließlich darf auch die System-Farbpalette im CBDraw()-Callback nicht verändert werden, der Server sollte seine Ausgabe nach Möglichkeit an die von ihm vorgefundene Palette anpassen.

Hat ein Server Veränderungen an einem Dokument vorgenommen, diese aber noch nicht gespeichert, kann er dem zugehörigen Client die Message OLGA_INPLACEUPDATE schicken, damit der Client die Bildschirmdarstellung sofort aktualisieren läßt. Beim Speichern eines Dokuments wird die Änderung automatisch vom OLGA-Manager per OLGA_UPDATE mitgeteilt.

### Objekte freigeben

Wenn ein Client ein Dokument schließt (was z.B. auch beim Beenden des Clients der Fall ist), muß er für jedes Objekt den CBUnembed()-Callback aufrufen, damit der Server feststellen kann, ob ein Dokument noch irgendwo als Objekt eingebunden ist. Analog muß sich der Server beim Client melden, allerdings macht letzterer dies mit der Message OLGA_UNEMBED.

Wenn ein Client OLGA_UNEMBED empfängt, kann er das zugehörige Objekt als ungültig markieren, indem er anstelle des eigentlichen Objekts z.B. einen leeren, rot durchgestrichenen Rahmen zeichnet.

Zusätzlich kann von einem Client die Message OLGA_SERVERTERMINATED und von einem Server OLGA_CLIENTTERMINATED beachtet werden, um die Gültigkeit von Objekten bzw. Verbindungen festzustellen.

### Ausblick

OLGA 1.2 hat nicht nur ID4, sondern auch die sogenannte Notification dazubekommen. Dies wird Thema des vierten Artikels der OLGA-Reihe sein. OLGA2 schließlich dürfte uns nächstes Jahr auch solche Dinge wie InplaceActivation bescheren, d.h. die Bearbeitung eines Dokuments innerhalb einer fremden Applikation.

### Bezugsquelle

Das OLGA-Archiv liegt in der Maus KA (0721-358887) und in der Maus FR (0761-381322) als OLGA.LZH (bzw. OLGAUSER.LZH ohne Debugversion und Quelltexte) sowie im WorldWideWeb auf

OLGA

Siehe auch id4.com

TM