Topic       : TOS - das Betriebssystem
Author      : 
Version     : tos.hyp (5. März 2013)
Subject     : Programmieren/Atari
Nodes       : 3001
Index Size  : 93602
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Titel
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File15.2.1  Aufruf von BubbleGEM                                       TOS

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: 0xBABB) an die ap_id ver- 
schicken und erhält BUBBLEGEM_ACK (0xBABC) 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 Los- 
lassen! 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]   0xBABB
 * 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 (0xBABC) mit dem Pointer 
auf die Zeichenkette, deren Speicher man nun bei Bedarf freigeben 
kann. Die Arrayelemente 2, 3, 4 und 7 sind ausgenullt. Beim nichtmoda- 
len Aufruf kommt das BUBBLEGEM_ACK erst nach dem Schließen der Blase!

/* BUBBLEGEM_ACK (0xBABC)
 *
 * msg[0]   0xBABC
 * 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.

Wenn bei BUBBLEGEM_SHOW das Bit BGS7_MOUSE (0x0004) in msg[7] gesetzt 
ist, werden die übergebenen Koordinaten nur zum Zeichnen verwendet; 
BubbleGEM ermittelt dann die Mauskoordinaten, anhand derer eine 
Bewegung der Maus erkannt wird (und die zum Schließen der Blase 
führt), kurz vor der Anzeige der Blase automatisch neu.

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 
BGS7_USRHIDE (0x0001) in msg[7].

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

Auf Systemen ohne wind_update()-Testmodus werden evtl. doppelte 
Hilfstexte angezeigt (direkt nacheinander). Dies ist derzeit leider 
nicht anders realisierbar.