Help balloons

Descriptive hover balloons appear when you hover over certain nodes in a diagram, displaying attribute values such as identifier, units, and help or description. These normally appear in browse mode but not in edit mode unless you've changed your personal preference.

Turning on/off

You control whether balloons display while using Analytica from the Edit → Preferences dialog setting. You can set them to display only in browse mode, in both browse and edit mode, or in neither. This is your personal preference setting, which applies to any Analytica session that you open. This preference is not stored with the model, and when others view your model, their own preference setting will be in force. The default when Analytica is first installed is for balloons to display in browse mode, but not in edit mode.

You can disable hover balloons for people who view your model in the Analytica Cloud Player (ACP) by specifying show_hover_balloon: no in the CloudPlayerStyles attribute. It would be unusual to do so, and we're not sure why you'd ever want to.

What Displays

Balloons only display for nodes that have value set for either the Help attribute or the Description attribute. If you've not filled in either, no balloon will display when users hover over your node.

The Help attribute takes precedence, providing the text in the balloon if present. Thus, if you want something other than the Description, all you have to do is fill in the Help attribute. In order to use the Help attribute, you have to first turn on its visibility by going to Object → Attributes... and placing a check next to Help. On the Attributes... dialog, there are three categories of objects. Make sure to turn it on for all categories. Once a check is placed next to Help in the Attributes... dialog, then Help will appear on the Object Window and in the attribute pane's list of attributes dropdown.

When the Help attribute is not present, then the Description, if present, is displayed.

Variable nodes display the identifier (the title is already visible on the diagram) and the units, if present, as a bold title line. Module nodes omit the title line.

Balloons for text nodes only display when a Help attribute is present. The Description attribute is already visible as the diagram text, and doesn't pop up separately as a balloon.

Customizing Balloon Content

It is possible to customize the behavior of descriptive balloons. You can control which nodes display balloons and which attributes are displayed with arbitrary logic, so that specifics could vary dramatically from node to node. When you customize the balloon logic, these changes are stored with your model.

To customize the logic, first open the typescript window by pressing F12 and type:

show object CustomizeBalloonHelp

This brings up the object window view for the system function CustomizeBalloonHelp. The definition attribute displays the default logic. To customize what displays, you simply edit the definition. As you edit the definition, it is important that the logic you add contain only operations that evaluate quickly. This logic must evaluate within a fraction of a second as the user hovers over node. Adding expressions that take several seconds to evaluate will serious damage the user experience!

The function CustomizeBalloonHelp provides three parameters:

«obj»: object
«isEditMode»: boolean
«actualObj»: object

The first parameter, «obj», is the underlying object. You can access any attributes of this object using Attrib of Obj. Hence, perhaps the simplest definition for CustomizeBalloonHelp would be:

Function CustomizeBalloonHelp(obj: object; isEditMode: boolean; actualObj: object)

Definition: description Of obj

You may use any Analytica functions or expression syntax in the logic. The «isEditMode» parameter indicates whether the user is in edit or browse mode. You can use this if you want the information to be different in the two modes.

The «actualObj» parameter is the same as «obj» for module and variable nodes. The two differ for alias, input and output nodes. For example, when a user hovers over the input node for variable Va1, «obj» will be Va1 while «actualObj» will be the actual input node object.

Return Value

The result for CustomizeBalloonHelp should be one of three things:

Null : Indicates that no balloon should display
«text» : Provides the text to display in the balloon
[«titleText», «text»] : A two-element list, both elements being text, will cause a bolded «titleText» to appear on the first line, with «text» appearing in the body of the balloon. The title text should fit on a single line and is limited to a maximum of 99 characters.

Example

As a guiding example, in this section we'll develop a non-trivial customization example and take you through each step. Our goal will be to display the title and units in bold, and then in the body we'll display the identifier only if it differs from the title, the description (if it exists), and the first 300 characters of the definition.

While all objects have an identifier, not all have a title. If there is no title, then we'll display the identifier in the title strip. So we start by obtaining this title text:

var theTitle := title of obj;

If IsNull(theTitle) Then theTitle := identifier of obj;

Those objects that do have a title often have a title that differs from the identifier only by having disallowed identifier characters (like spaces) converted to underscores. Hence, the node may have the title "Net revenues" and the identifier "Net_revenues" which are essentially the same. When they are essentially the same, we don't want to display the identifier in the body. Hence, we want to detect whether they are fundamentally different:

 var identFromTitle := TextReplace(theTitle, "[^\w_]", "_", all: true, re: true);
 var newl := "
 ";
 var body := If TextLowerCase(identFromTitle) <> TextLowerCase(identifier of obj) Then "Identifier: " & (identifier of obj) & newl Else "";

Next, we want to include the units in the title strip:

If Not IsNull(units of obj) Then theTitle := " (" & (units of obj) & ")";

Include the description and definition, if they exist. In the case of the definition, we'll truncate at 300 characters, and then we'll indent:

 If Not IsNull(description of obj) Then body := body & description;
 var defn := SelectText(definition of obj, 1, 300);
 If TextLength(definition of obj) > 300 then defn := defn & "...";
 defn := TextReplace(defn, "\n", "\n            ", all: true, re: true);   { indent }
 If Not IsNull(definition of obj) Then 
    body := body & newl & "Definition:" & defn;

Finally, we return two text values, the first being the bolded title text, the second the unbolded body text:

[theTitle, body]

So, putting it all together, we have:

 Function CustomizeBalloonHelp(obj: object; isEditMode: boolean; actualObj: object)
 '''Definition:''' 
   var theTitle := title of obj;
   If IsNull(theTitle) Then theTitle := identifier of obj;
   var identFromTitle := TextReplace(theTitle, "[^\w_]", "_", all: true, re: true);
   var newl := "
   ";
   var body := If TextLowerCase(identFromTitle) <> TextLowerCase(identifier of obj) Then "Identifier: " & (identifier of obj) & newl Else "";
   If Not IsNull(units of obj) Then theTitle := theTitle & "   (" & (units of obj) & ")";
   If Not IsNull(description of obj) Then body := body & (description of obj);
   var defn := SelectText(definition of obj, 1, 300);
   If TextLength(definition of obj) > 300 then defn := defn & "...";
   defn := TextReplace(defn, "\n", "\n            ", all: true, re: true);   { indent }
   If Not IsNull(definition of obj) Then 
      body := body & newl & "Definition:" & defn;
   [theTitle, body]

Tricks

You can debug your function in the same way you can any other User-Defined Functions. You can call it from a variable with parameters that you supply. So, while debugging, you may want to ensure balloon help is off from edit mode.

You can call other User-Defined Functions from the definition. Hence, if your logic gets too complex, you can divide it across multiple functions.

Your logic can be conditional on the object's class. For example, you may want to show information differently for Function nodes, variables, modules, text and pictures. To get the object class, simply use class of obj. E.g.:

If class of obj = "Function" Then body := body & "(" & (ParamNames of obj) & ")" & newl

History

Introduced in Analytica 4.4.