Difference between revisions of "Help balloons"

(Balloon Help, first draft)
 
(Customizing Balloon Content)
Line 26: Line 26:
  
 
== Customizing Balloon Content ==
 
== 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:
 +
::<code>show object CustomizeBalloonHelp</code>
 +
 +
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:
 +
::'''Parameters:'''  <code>(obj : object ; isEditMode : boolean ; actualObj : object )</code>
 +
 +
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.

Revision as of 00:46, 6 September 2011

new to Analytica 4.4

Hover balloon.png

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

Preferences-balloons.png

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 over 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:

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.
Comments


You are not allowed to post comments.