MUSHclient scripting

Each miniwindow can have any number of hotspots (including zero). Each one designates a rectangle which has some significance if you mouse over it, or click inside it. You should take care not to overlap hotspot rectangles or they may not behave as you expect. When checking for mouse clicks, hotspots are evaluated in ascending alphabetic order by hotspot id.

Hotspots are not, in themselves, visible graphic elements. You would normally associate them with a piece of text (for a hyperlink) or a graphical element such as a button or checkbox. For example, when drawing text, you know the starting point of the text, the height of the text, and the width of the text. This can be used to create a hotspot over the same place the text appeared.

Most of the functionality of hotspots is provided by script "callbacks" - that is, when you mouse over a hotspot, a function in your main script file, or plugin, is called (if you nominate one).

NOTE: Hotspot functions must be visible to MUSHclient when querying the script engine. Thus functions declared as "local" in Lua (or something similar in other languages) will not work.

WARNING: If you set the "draw underneath" flag when calling WindowCreate, then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

WARNING: If you set the "ignore mouse" flag when calling WindowCreate, then you cannot use hotspots, as mouse clicks and movement will not be detected.

If you want to handle dragging (moving the mouse after clicking), see also WindowDragHandler.

For more information, see:

http://www.gammon.com.au/mushclient/mw_hotspots.htm

This create a hotspot in the miniwindow, and remembers it by the nominated "hotspot id".

WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id to be associated with this particular hotspot. Hotspot IDs are case-sensitive.

Left, Top, Right, Bottom - describes the hotspot rectangle.

MouseOver - the name of the script function to be called when you mouse over the hotspot rectangle

CancelMouseOver - the name of the script function to be called when you move the mouse away from the hotspot rectangle

MouseDown - the name of the script function to be called when you mouse down in the hotspot rectangle

CancelMouseDown - the name of the script function to be called when you release the mouse not in the hotspot rectangle that the mouse-down occurred in

MouseUp - the name of the script function to be called when you release the mouse in the hotspot rectangle that the mouse-down occurred in

TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text.

To change a tooltip later, see: WindowHotspotTooltip

Cursor - a number which indicates what shape the mouse pointer is to take when over the hotspot, as follows:

-1: no cursor

0: arrow
1: hand
2: I-beam
3: + symbol
4: wait (hour-glass)
5: up arrow
6: arrow nw-se
7: arrow ne-sw
8: arrow e-w
9: arrow n-s
10: arrow - all ways
11: (X) cannot do action
12: help (? symbol)

Flags - flags to modify hotspot behaviour. These should be or'd together.

0x01 : All mouse-over events are reported to the mouseover callback (if any)

For subsequent mouse-overs within a single hotspot the flags will have the 0x80 bit set. For the first mouse-over the 0x80 bit will be clear.


The callback functions should look like this:


function mouseover (flags, hotspot_id)
Note ("we moused over hotspot " .. hotspot_id)
return 0 -- needed for some languages
end -- mouseover

Since the hotspot ID is passed to the callback function, you can share the same function amongst all your hotspots. For example, a "mouse down" function could handle all the hyperlinks in a miniwindow - by using the hotspot ID, it could look up in a table what action to perform for this particular hotspot.

The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.

The flags parameter is a bit mask as follows:

0x01 - Shift key down
0x02 - Control key down
0x04 - Alt key down
0x10 - LH mouse
0x20 - RH mouse
0x40 - double-click
0x80 - mouse-over not first time
0x100 - scroll wheel scrolled (towards you)
0x200 - middle mouse

So, for example, if the left-hand mouse was double-clicked whilst the shift and control keys were held down, the flags would be:


flags = 0x01 + 0x02 + 0x10 + 0x40 --> namely 0x53 (83 in decimal)

You could test this in Lua like this:

if bit.band (flags, 0x20) ~= 0 then
-- mouse be RH mouse
end -- if


WARNING: The hotspot callbacks are not functions, but names of functions. That is, they should be supplied as string arguments. The supplied names are looked up in the script space at the appropriate time.

WARNING: The hotspot callbacks have to be in the same script space as each other (either all in the same plugin, or the world script file).

Note: Available in version 4.34 onwards.