WinDom: BubbleGEM Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# 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().