popuphelp - Function

add popup help to a GUI

Synopsis
popuphelp(fr, txt, hlp, combi, width) include "popuphelp.g"

Description
popuphelp Is a function which adds the code necessary to add ``popup'' help to an agent. In particular, when your cursor ``lingers'' or ``hovers'' over that agent (e.g. a button) for more than about half a second, the help will popup, and go away when the cursor leaves the agent or when a button is pushed, etc. Help text comes in two flavours: short and long. If only one of them is available, they will both be identical. Short help is displayed on one line if it is not longer than the specified width (60 by default), else on several lines. If no explicit long help is present, the shorthelp is truncated at a new line or at a period, and will never be longer than the specified width. If the longhelp differs from the shorthelp (either by truncation or otherwise), the shorthelp is extended with ``..'' at the end of the displayed short text.

Short help is displayed by default when the cursors hovers above the agent. Long help is tied to the right mouse button by default.

Popup help can, dynamically, be tied by setting the 'system.help.type' to 0 (no popup), 1(short and long), 2(long only with MB3), 3(long only in hover).

A ``popupmenu'' function is also available to add a ``?'' button to your GUI which let the user choose the context popup type action. If a popupmenu is generated, the default can be set with the aipsrc variable ``help.popup.type'' (possible values: 'none', 'both', 'mb3long' and 'hoverlong'), or by the programmer.

For most popup help items you merely specify a text string that is the help text. For a listbox, you can supply a callback function that takes two arguments and returns a string. The two supplied arguments are:

1.: the text of the listbox item the cursor is near; and
2.: the Y-index (0 relative!) of the cursor position in the listbox.

It should be noted that timing errors could crash the system (or leave popuphelp floating around) if an agent that supports popuphelp is just zeroed (e.g. by frameagent :=F). A function 'popupremove(agent)' exists to do a proper zeroing.

Arguments

fr	agent to which popup text should be added
	Allowed:	record or agent
txt	popup text, or, for listbox, possible callback routine
	Allowed:	string or function as described above
	Default:	F
hlp	optional separate short help text, or,for listbox, possible callback routine
	Allowed:	string or function as described above
	Default:	F
combi	specifies if short text should precede long text
	Allowed:	bool
	Default:	F
width	specifies maximum length of one shorthelp line
	Allowed:	integer
	Default:	60

Returns
T (or fail)

Example

include 'popuphelp.g';
private := [=];
private.f := frame(height=100);
private.b := button(private.f);
popupmenu(private.f);  # to add a ? menu button (if wanted)
popuphelp(private.b, 'Press the button, and make this a long text');
private.l := listbox(private.f);
private.l->insert('AAA'); private.l->insert('BBB');
private.l.helpfct := function(name, index) {
    # Only need name here.
    return spaste('Your cursor is near ', name);
}
popuphelp(private.l, private.l.helpfct);

Next: popupremove - Function Up: guiutils - Module Previous: displaylisttest - Function Contents Index

	Package	display
	Module	guiutils