Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File13.2.1  How to call BubbleGEM?                                     TOS

There are two fundamental ways to call BubbleGEM. The following 
example code snippet describes the simplest way to call BubbleGEM from 
non-modal dialogs and window-dialogs. Since BubbleGEM Release 05 it's 
now also possible to call BubbleGEM from modal dialogs.

Before every Bubble-call, supporting applications search via 
appl_find("BUBBLE ") for the BubbleGEM AES application identification 
number (bubble_id). Once the AES ID has been received, a message 
BUBBLEGEM_SHOW (hexadecimal: 0xBABB) can be sent to the ap_id and 
should receive a BUBBLEGEM_ACK (0xBABC) message in reply.

It is important the character string passed is NULL-terminated, 255 
characters maximum and global legible - otherwise this leads to memory 
corruption in systems with memory protection. Always request global 
memory.

The message BUBBLEGEM_SHOW should be sent out as soon as the the right 
mouse button is pressed - don't wait until the button is released!

The mouse coordinates are passed using x and y and these are used to 
determine where the speech bubble will be drawn. Calls for BubbleGEM 
may only be instigated from non-modal dialogs.

Changes to BubbleGEM bubbles are updated automatically, however, you 
can intervene manually using the vertical line "|" character. 
Preceding or following space characters are not necessary.

C example:

#include <portab.h>

/* BUBBLEGEM_SHOW - Message:
 * msg[0]   0xBABB
 * msg[1]   ap_id
 * msg[2]   0
 * msg[3]   mouse X
 * msg[4]   mouse Y
 * msg[5/6] to NULL-terminated character string in global memory
 * 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;

/* Establish if Mxalloc() is available, if yes,
 * then memory protection mode is set to "Global"
 */
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 invalid, no memory there */
        return;

if (right_mouse key_button_pressed)
{
    /* fill buffer */
    strcpy(bubble_text, "My first help speech bubble.");

    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)
        {
            /* Error */
        }
    }
}

A reply message BUBBLEGEM_ACK (0xBABC) is received with the pointer to 
the character string, whose memory can now be released. The array 
elements 2, 3, 4 and 7 are set to null (zeroed). On non-modal calls 
the BUBBLEGEM_ACK comes only after closing the bubble!

/* BUBBLEGEM_ACK (0xBABC)
 *
 * msg[0]   0xBABC
 * msg[1]   ap_id
 * msg[2]   0
 * msg[3]   0
 * msg[4]   0
 * msg[5/6] Pointer from BUBBLEGEM_SHOW
 * msg[7]   Same value as msg[7] on sending BUBBLEGEM_SHOW;
 *          presently 0.
 */

/* example code snippet */

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

if (pointer)
  Mfree(pointer)

To make translation into other languages easier, please consider 
storing the character strings externally, for example in the resource 
file (RSC) or a separate ASCII file.

If on BUBBLEGEM_SHOW the bit BGS7_MOUSE (0x0004) in msg[7] is set, the 
passed coordinates are only used for drawing; BubbleGEM ascertains the 
mouse coordinates, which can be used to recognize mouse movement 
(leading to bursting the bubble) shortly before automatically re- 
displaying the bubble.

The procedure to call BubbleGEM from modal dialogs (see also the call 
routine) proceeds similarly to calls from non-modal dialogs, assuming 
the BGEM cookie is available, except BGS7_USRHIDE (0x0001) is set in 
pipe[7] instead.

Additionally, after evaluating the mouse coordinates through the 
calling application, BUBBLEGEM_HIDE (0xbabf) must be sent to 
BubbleGEM. The evaluation of the mouse and keys on calling modal 
dialogs is the responsibility of the calling application.

On systems without wind_update, testmode is possible. Double help 
texts can be displayed (directly above one another). Currently this is 
not possible otherwise.