New event: EvtHelpTip

Many suggestions for conzept 16 relate to the modification of help tips before they are displayed or to a reaction to sub-objects. In order to be able to realize this, the new event EvtHelpTip will be made available in the next version 5.7.08, which offers the programmer the desired options. I would like to introduce you to this event below.

Case studies

• Helptip at row / cell level for lists
• Different help tips per axis of a GanttGraph object
• Help tips per page in the DocView and PrtJobPreview object

Structure and call

The EvtHelpTip event can be entered for all objects that have the wpHelpTip property and for which events can be entered.

EvtHelpTip is triggered for the first time when the mouse is moved over an object and no help tip is currently displayed. If a help tip is already displayed, the event is only triggered again if one of the arguments aHitTest, aItem and aID changes.

Longer procedure processing should be avoided for the EvtHelpTip event, as no user actions are possible during this time and no other events are triggered. The event is triggered within an object at most every 250 milliseconds. It is triggered directly when switching to another interface object.

sub EvtHelpTip
(
  aEvt                  : event;        // Event (in)
  aButton               : int;          // Additional buttons (in)
  aHitTest              : int;          // Hittest code (in)
  aItem                 : handle;       // Column or Gantt interval (in)
  aID                   : int;          // RecID for RecList / cell for GanttGraph / print object for PrtJobPreview (in)
  aNameID               : alpha;        // Name ID (in)
  aText                 : alpha(4096);  // HelpTip to be displayed (in / out)
  aJustify              : int;          // Alignment of the HelpTip (in / out)
)
: logic;                                // Show HelpTip?

Some of the passed arguments (AaButton, aHitTest, aItem und aID) are already known from the EvtMouseItem event. They help to identify any subordinate objects. In aHitTest, the respective object type is transferred for objects with subordinate objects. The argument aItem provides the descriptor of the sub-object for certain objects, for example the descriptor of the column for lists. In aID, line or page numbers, record IDs or cell positions are transmitted.

For StoList and StoListPopup objects, the name of the application resource over which the mouse is positioned is transferred in aNameID.

The arguments aText und aJustify contain the current values of the properties wpHelpTip and wpHelpTipJustify. These arguments can be changed in the event, thereby modifying the help tip to be displayed. The properties themselves remain unchanged.

If aText is empty when the event is ended, or if false is returned, no help tip is displayed.

Subordinate objects

The following objects have subordinate objects:

• DataList, RecList, StoList
  Header area(_WinHitLstHeader), Data range (_WinHitLstView)
• DataListPopup, RecListPopup, StoListPopup
  Data range (_WinHitLstView)
• DocView
  Page area (_WinHitDocViewPage), Empty display area (_WinHitNone)
• GanttGraph
  Corner between the axes (_WinHitCorner), Axes (_WinHitAxis), View area (_WinHitGanttView), Intervals (_WinHitIvl, _WinHitIvlLeft, _WinHitIvlRight), Boxes (_WinHitIvlBox, if option _WinGanttIvlBoxClick is set in wpGanttFlags, otherwise _WinHitGanttView)
• PrtJobPreview
  Side area (_WinHitPrtPage), Empty display area (_WinHitNone)
• RecNavigator
  _WinHitRecNavPrev, _WinHitRecNavNext, _WinHitRecNavPgUp, _WinHitRecNavPgDn, _WinHitRecNavFirst, _WinHitRecNavLast, _WinHitRecNavNew, _WinHitRecNavDel, _WinHitRecNavSave, _WinHitRecNavLock, _WinHitNone
• RecView
  Header area (_WinHitGroupColumn), Data range (_WinHitGroup), Empty display area (_WinHitLstView)
• TreeView
  TreeNode (_WinHitTreeNode), Empty display area (_WinHitNone)

Special cases

• There are objects that have the wpHelpTip property, but for which no events can be entered. Two of these objects are toolbar buttons and status bar buttons. If the wpHelpTip property is set for the button, this is preferred over the wpHelpTip of the toolbar or status bar. If the EvtHelpTip is also set for the tool or status bar object, the help tip to be used is transferred to the event and can be changed there.
• For the DataList and RecList objects, there are differences between EvtMouseItem and EvtHelpTip in the common arguments. With EvtMouseItem, the RecID / number of the selected line is always transferred in aID, whereas in EvtHelpTip it is always the one over which the mouse is positioned.
• In Calendar objects, the date converted to int (CnvID()), over which the mouse pointer is positioned, is transferred in aID.
• With the PrtJobPreview object, EvtHelpTip is also triggered if the mouse pointer is not positioned over a page. In this case, the arguments aHitTest = _WinHitNone, and aItem and aID = 0.
• Objects whose property wpDisabled is set to true do not receive an EvtHelpTip. In this case, no help tip is displayed. This also affects list objects whose property wpLstStyle is set to _WinLstHeaderStatic.