Element: gstructure.ebrowse

Type

callback

Description

The class callback method for gstructure objects, invoked when entity browsing is active in a graphic window.

Entity browsing is a facility which displays descriptive tooltips as the mouse passes over entities within a graphic window. Whenever the mouse passes over an entity, the .ebrowse callback is invoked, which sets the tooltip text and the tooltip is then displayed. Browsing is activated by setting the window.browsing attribute of the appropriate graphic window.

The .ebrowse callback(s) must be defined for tooltips to be displayed. These callbacks are defined at a class level, rather than on individual entities and may be defined for gstructure classes, compound classes or just the generic entity class, i.e. entity.ebrowse.

The gstructure object being passed over, and a glabel entity is passed to the callback, wherein the tooltip position, symbology, textstyle and text may be set. If no text is set, then no tooltip is displayed.

Once the callback has been executed, the tooltip glabel gets displayed (if it contains valid text). The window's overlay group (window.overlay) is used for the tooltip display. This is done behind the scenes.

During browsing, the system does the equivalent of an epick on the window and only invokes the .ebrowse callback if the gstructure object is not filtered out during the pick (see window.pick_group, window.pick_filter etc.)

For compound objects or standard entities to be active during browsing, they must have class .ebrowse callbacks of their own defined. If a gstructure class has no .ebrowse callback defined, then no tooltip is shown during browsing.

Examples

For details of parameters passed to a .ebrowse callback see entity.ebrowse.

Consider a gstructure which represents restaurants:

gstructure ~mytab.restaurant {
   string title
   string phone
   string cuisine
   string address[3]
}

In your graphic window, you might be displaying a layout of restaurants on top of a street map, and as the mouse passes over them you may want to know the restaurant name, the style of cuisine and the phone number. A .ebrowse callback for this class would then be:

gstructure ~mytab.restaurant.ebrowse = {
   args me=epointer, tt=epointer, gw=window
   tt.text[1] = me.cuisine
   tt.text[2] = me.title
   tt.text[3] = me.phone
}

You could vary the color according to the style of cuisine, e.g.

gstructure ~mytab.restaurant.ebrowse = {
   args me=epointer, tt=epointer, gw=window
   tt.text[1] = me.cuisine
   tt.text[2] = me.title
   tt.text[3] = me.phone
   switch (me.cuisine) {
      case 'thai': { tt.fill = pink }
      case 'chinese': { tt.fill = orange }
      case 'french': { tt.fill = green }
      case 'indian': { tt.fill = khaki }
   }
}

On display there might also be hotels and cinemas, represented by different gstructures. You could have different styles of tooltip for these, by defining .ebrowse callbacks for the relevant hotel and cinema gstructure classes.

Note: This callback will not be invoked for simple entities or compounds, for which different .ebrowse class callbacks must be defined.

See Also