Help balloons

When you move your cursor over a node in a diagram in browse mode, it a balloon appears showing the Description of the object (if it has one). You can control whether or when the balloon appears in desktop Analytica and ACP, and include other attributes.

Turning on/off

By default, help balloons appear in Browse mode but not in Edit mode in desktop Analytica, and always in ACP (which has no edit mode). No balloon appears if the Object has no specified Description (or Help) attribute. You can set balloons to display also in Edit mode, or never, in the Edit → Preferences dialog.

This is your personal preference setting, so it applies to any Analytica session that you open on your computer. It is not stored with the model, and so will not apply to other people when they view your model on their computer.

In Analytica Cloud Platform (ACP), you can stop help balloons (for all users) by specifying show_hover_balloon: no in the AcpStyles attribute of the model. But, we're not sure why you'd want to.

What Displays

By default, a help balloon in Analytica Desktop shows the object's title and units (if any) in a heading at the top (but not in ACP), with the Description below (in either platform).

If the object has a "Help" attribute, that appears instead of the "Description". So, by adding a "Help" attribute, you prevent showing the "Description". This is useful when you want to show help for end users that is different from the Description intended for model developers.

In order to use the Help attribute, you have to first turn on its visibility in the Manage attributes#Attributes dialog and placing a check next to Help. The Attributes... dialog has three categories of objects: Variables, Functions, and Modules. Make sure to turn it on for all three. Once a check is placed next to Help in the Attributes... dialog, then Help appears on the Object Window and in the attribute pane's attributes dropdown menu.

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

Customize balloon with CustomizeBalloonHelp()

You can customize which attributes appear in a balloon and when with arbitrary logic. You can vary its behavior by node type or even for individual nodes. This logic is stored with your model (not as a Personal preference) as the Definition of the built-in Function CustomizeBalloonHelp(). It returns the text to be displayed in a Balloon.

To customize the logic, first open the typescript window by pressing F12 or Ctrl+' and type:

Show object CustomizeBalloonHelp

This brings up the object window view for the system function CustomizeBalloonHelp. Its definition contains the default logic. To customize what displays, you simply edit the definition. This logic must evaluate within a fraction of a second as the user hovers over node, so it is important that it can evaluate quickly. Adding an expression that takes 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. 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 original object for alias, input and output nodes. («actualObj» is the same as «obj» for other node types.) When you move the cursor 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 list of two text values causes «titleText» to appear as a bold title 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 an example, this section shows a non-trivial customization example and takes 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]

Tips

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. While debugging, you may want to ensure balloon help is off from edit mode.

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

The logic can depend 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.