Aufruf von BubbleGEM

Grundsätzlich gibt es zwei Möglichkeiten, BubbleGEM aufzurufen. In den direkt folgenden Abschnitten wird der Aufruf aus unmodalen Dialogen, also aus Fensterdialogen, beschrieben, der am einfachsten ist. Seit der Release 05 kann man BubbleGEM nun aber auch aus modalen Dialogen aufrufen.

Als modernes Programm sucht man vor jedem Bubble-Aufruf per appl_find("BUBBLE ") die AES-Applikations-Identifikationsnummer (kurz: bubble_id) von BubbleGEM. Hat man die AES-ID erhalten, kann man die Nachricht BUBBLEGEM_SHOW (hexadezimal: $BABB) an die ap_id verschicken und erhält BUBBLEGEM_ACK ($BABC) zurück.

Wichtig ist, daß die übergebene nullterminierte Zeichenkette maximal 255 Zeichen lang sein darf und daß sie global lesbar sein muß. In Systemen mit Speicherschutz kommt es sonst zu Schutzverletzungen, was die Professionalität Ihres Programms nicht gerade unterstreichen würde. Daher unbedingt globalen Speicher anfordern!

Die Nachricht BUBBLEGEM_SHOW sollte bereits losgesandt werden, wenn die rechte Maustaste heruntergedrückt wurde, nicht erst beim Loslassen! Mit x und y übergibt man die Mauskoordinaten, an deren Stelle die Sprechblase dann gezeichnet wird.

Ein Umbruch in der Blase wird von BubbleGEM automatisch vorgenommen, wer trotzdem manuell eingreifen will, kann den senkrechten Strich "|" dafür verwenden. Leerzeichen davor oder dahinter sind nicht notwendig.

Ein kleines Beispiel in C:

#include <portab.h>

/* BUBBLEGEM_SHOW - Nachricht:
 * msg[0]   $BABB
 * msg[1]   ap_id
 * msg[2]   0
 * msg[3]   Maus X
 * msg[4]   Maus Y
 * msg[5/6] Pointer auf nullterminierte Zeichenkette im globalen
 *          Speicher
 * msg[7]   0
 */

...

#define MGLOBAL     0x20

#define BUBBLEGEM_REQUEST  0xBABA
#define BUBBLEGEM_SHOW     0xBABB
#define BUBBLEGEM_ACK      0xBABC
#define BUBBLEGEM_ASKFONT  0xBABD
#define BUBBLEGEM_FONT     0xBABE
#define BUBBLEGEM_HIDE     0xBABF

#define MagX_COOKIE     0x4D616758L
#define MiNT_COOKIE     0x4D694E54L
...

WORD msg[8];
WORD bubble_id;
BYTE *bubble_text;

/* Feststellen, ob Mxalloc() vorhanden ist, wenn ja,
 *  dann Speicherschutz-Modus auf "Global" setzen
 */
if ((get_cookie (MagX_COOKIE, &val) == TRUE) ||
   (get_cookie (MiNT_COOKIE, &val) == TRUE))
{
  bubble_text = (BYTE *) Mxalloc (256, 0 | MGLOBAL);
}
else
  bubble_text = (BYTE *) Malloc (256);

if (!bubble_text)   /* Pointer ungültig, kein Speicher da */
  return;

if (rechte_maustaste_ueber_button_gedrueckt)
{
  /* Puffer füllen */
  strncpy(bubble_text, "Meine erste Sprechblasenhilfe.", 255);

  bubble_id = appl_find("BUBBLE  ");

  if (bubble_id >= 0)
  {
    msg[0] = BUBBLEGEM_SHOW;
    msg[1] = ap_id;
    msg[2] = 0;
    msg[3] = x;
    msg[4] = y;
    msg[5] = (WORD)(((LONG) bubble_text >> 16)
             & 0x0000ffff);
    msg[6] = (WORD)((LONG) bubble_text & 0x0000ffff);
    msg[7] = 0;
    if (appl_write(bubble_id, 16, msg) == 0)
    {
      /* Fehler */
    }
  }
}

Als Antwortnachricht erhält man BUBBLEGEM_ACK ($BABC) mit dem Pointer auf die Zeichenkette, deren Speicher man nun bei Bedarf freigeben kann. Die Arrayelemente 2, 3, 4 und 7 sind ausgenullt. Beim nichtmodalen Aufruf kommt das BUBBLEGEM_ACK erst nach dem Schließen der Blase!

/* BUBBLEGEM_ACK ($BABC)
 *
 * msg[0]   $BABC
 * msg[1]   ap_id
 * msg[2]   0
 * msg[3]   0
 * msg[4]   0
 * msg[5/6] Pointer aus BUBBLEGEM_SHOW
 * msg[7]   Gleicher Wert wie msg[7] beim Senden von BUBBLEGEM_SHOW;
 *          derzeit 0.
 */

/* kurzer Beispielcode */

pointer = *(BYTE **) &msg[5];

if (pointer)
  Mfree(pointer);

Zu bedenken ist, daß man die Zeichenketten am besten extern auslagert, damit Übersetzungen in andere Sprachen leichter fallen - also am besten ins Resource-File oder eine separate ASCII-Datei damit.

Der Aufruf aus modalen Dialogen (siehe auch die Aufrufroutine) erfolgt wie bei den unmodalen, vorausgesetzt, daß der BGEM-Cookie vorhanden ist. Man setzt im Gegensatz zum Aufruf aus unmodalen Dialogen jedoch ist BGS7_USRHIDE ($0001) in pipe[7].

Außerdem muß nach der Mausauswertung durch die aufrufende Applikation BUBBLEGEM_HIDE ($babf) an BubbleGEM geschickt werden. Die Auswertung der Maus- und Tastenereignisse muß die Applikation beim Aufruf aus modalen Dialogen selbst übernehmen.