BubbleGEM Library
[Reference documentation]

Group of functions devoted to handle efficiently the BubbleGEM system. More...

Defines

#define BubbleConf(a)

Functions

int mt_BubbleCall (APPvar *app, char *help, int x, int y)
 Display a bubble help.
int mt_BubbleModal (APPvar *app, char *help, int x, int y)
 Display a bubble help in a classic formular.
int mt_BubbleDo (APPvar *app, OBJECT *tree, int __index)
 alternative FormDo() function for BubbleGEM
int mt_BubbleAttach (APPvar *app, OBJECT *tree, int __index, char *help)
 Link a bubble help to an object.
void mt_BubbleFree (APPvar *app)
 release memory reverved by BubbleAttach().
int mt_BubbleFind (APPvar *app, OBJECT *tree, int __index, char **help)
 Find a bubble linked to an object.
int mt_BubbleEvnt (APPvar *app)
 display the bubble help defined by BubbleAttach().
int mt_BubbleGet (APPvar *app)
 load the BubbleGEM daemon in memory

Detailed Description

Group of functions devoted to handle efficiently the BubbleGEM system.

Define Documentation

#define BubbleConf (  a   ) 
 

Function Documentation

int mt_BubbleAttach (  APPvar *  app,
OBJECT *  tree,
int  index,
char *  help
) 
 

Link a bubble help to an object.

Parameters:
app application descriptor,
tree address of an objects tree,
index object index,
help address of string to display in the bubble (the string is not duplicated)
Returns:
0 (success) or -1 (memory error).
This function links a bubble help to an objet in a window formular or a toolbar. The bubble will be displayed by the mt_BubbleEvnt() function, typically after a timer event or a right mouse button event. When the program terminates, the bubbles should be free up with the mt_BubbleFree() function.

See also:
mt_BubbleEvnt(), mt_BubbleFree(), mt_BubbleFind().

int mt_BubbleCall (  APPvar *  app,
char *  help,
int  x,
int  y
) 
 

Display a bubble help.

Parameters:
app application descriptor,
help pointeur to the string to display in a bubble
x,y coordinates of the bubble (use the mouse position)
Returns:
0 (success) or one of the following error code :
  • (-1) bubbleGEM not loaded
  • (-2) the environment variable "BUBBLE=" is wrong
  • (-3) memory allocation error
mt_BubbleCall() sends a message to BUBBLE.APP to display a bubble help. If BUBBLE.APP is not loaded, mt_BubbleCall() tries to load it using the PATH or BUBBLE or BUBBLEGEM environ variables. This function just display a bubble help. It is possible to attach a bubble help to an object from a formular or a toolbar and display them systematically. For that purpose, see the mt_BubbleAttach() and mt_BubbleEvnt() functions.

The AES should not be stopped, that is the case with classic formulars which make use of wind_update() function, when the mt_BubbleCall() function is invoked. However, it is possible to call BubbleGEM from a classic formular with the mt_BubbleModal() function.

Note:
A '|' character forces a carriage return inside the bubble help
See also:
mt_BubbleAttach(), mt_BubbleEvnt(), mt_BubbleFree(), mt_BubbleFind().

int mt_BubbleDo (  APPvar *  app,
OBJECT *  tree,
int  edit
) 
 

alternative FormDo() function for BubbleGEM

Parameters:
app,tree,edit see mt_FormDo().
see mt_BubbleModal() for details

See also:
mt_BubbleModal().

int mt_BubbleEvnt (  APPvar *  app  ) 
 

display the bubble help defined by BubbleAttach().

Parameters:
app application descriptor
Return values:
0 if bubble is not found
WS_FORM if bubble is found in a dialog box
MW_TOOLBAR if bubble is found in a toolbar
This function finds the object pointed by the mouse sprite. If an object is found and if a bubble help is linked to this object (with mt_BubbleAttach()) the bubble help is displayed. mt_BubbleEvnt() works only with window formular or toolbar.

#include <windom.h>

void RightButton( void) {
    if( evnt.mbut & 0x2)
        BubbleEvnt();
}

int main(void) {
    OBJECT *tree;
    
    ApplInit();
    RsrcLoad( "TEST.RSC");
    rsrc_gaddr( 0, FORM1, &tree);
    
    // Link the bubble help to objects ...
    BubbleAttach( tree,  0, "Formular background");
    BubbleAttach( tree, OK, "An exit button"); 
    
    // Create form
    FormCreate( tree, MOVER|NAME, NULL, "test", NULL, 1, 0);

    // Handle globally the MU_BUTTON event
    EvntAttach( NULL, WM_XBUTTON, RightButton);

    do
        EvntWindom( MU_MESAG|MU_BUTTON);
    while( wglb.first);

    BubbleFree();  // release the bubbles
    RsrcFree();
    ApplExit();
    return 0;
}

See also:
mt_BubbleAttach(), mt_BubbleFree(), mt_BubbleFind(), W_FORM

int mt_BubbleFind (  APPvar *  app,
OBJECT *  tree,
int  index,
char **  help
) 
 

Find a bubble linked to an object.

Parameters:
app application descriptor,
tree address of an objects tree,
index object index,
help will be filled-in with the address of the string to display in the bubble
Returns:
1 if a bubble is found, 0 otherwise.
mt_BubbleFind() is called by mt_BubbleEvnt() to find the text to display in a bubble help. It can be used to find a bubble and display it with mt_BubbleCall() if you are not interesting to use mt_BubbleEvnt().

See also:
mt_BubbleCall(), mt_BubbleEvnt(), mt_BubbleAttach()

void mt_BubbleFree (  APPvar *  app  ) 
 

release memory reverved by BubbleAttach().

Parameters:
app application descriptor,
See also:
mt_BubbleAttach()

int mt_BubbleGet (  APPvar *  app  ) 
 

load the BubbleGEM daemon in memory

Parameters:
app application descriptor,
Returns:
the AES application ID of bubbleGEM, or a negative value if bubbleGEM is not loaded
mt_BubbleGet() loads if needed BUBBLE.APP, the BubbleGEM daemon, in memory and returns its AES app-id. Its uses the AES environ variable 'BUBBLE=' and 'BUBBLEGEM=' to locate the program. A search in 'PATH=' folders is performed too. mt_BubbleGet() is called because a mt_BubbleModal() call.

See also:
mt_BubbleModal(), mt_BubbleCall().

int mt_BubbleModal (  APPvar *  app,
char *  hlp,
int  mx,
int  my
) 
 

Display a bubble help in a classic formular.

Parameters:
app application descriptor,
hlp pointeur to the string to display in a bubble
mx,my coordinates of the bubble (use the mouse position)
Returns:
0 (success) or a negative error code :
mt_BubbleModal() is the equivalent function of mt_BubbleCall() function in the case of classic formulars (i.e. a formular stopping AES events). This function works only from BubbleGEM R05. With former version of BubbleGEM, it is not possible to call BubbleGEM from a classic formular.

If BUBBLE.APP is not present in memory, mt_BubbleModal() is not able to load it (because AES is stopped). So the BubbleGEM daemon can be launched prevously with the BubbletGet() function.

Because the form_do() function can not handle the right mouse button event, WinDom offers an alternative function to display systematically bubbles with mt_BubbleAttach() and mt_BubbleEvnt() functions : it is the mt_BubbleDo() function. This function is not universal, for custom usage, write your own mt_BubbleDo() function (looking at the mt_BubbleDo() source code. This function is simple, it uses the functions of the AES form library.

A complet example is given is the folder EXAMPLES/BUBBLE of the WDK package.

See also:
mt_BubbleGet(), mt_BubbleDo(), mt_BubbleAttach().

Generated on Thu Jun 22 11:45:28 2006 for WinDom by  doxygen 1.4.6