[Home] [Downloads] [Search] [Help/forum]

MUSHclient scripting

Description of MUSHclient world function: world.WindowAddHotspot


Name WindowAddHotspot
Type Method
Summary Adds a hotspot to a miniwindow
Prototype long WindowAddHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom, BSTR MouseOver, BSTR CancelMouseOver, BSTR MouseDown, BSTR CancelMouseDown, BSTR MouseUp, BSTR TooltipText, long Cursor, long Flags);

View list of data type meanings

Description

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.


Lua example
WindowAddHotspot(win, "hs1",  
                 10, 10, 60, 20,   -- rectangle
                 "mouseover", 
                 "cancelmouseover", 
                 "mousedown",
                 "cancelmousedown", 
                 "mouseup", 
                 "Click here to be healed",  -- tooltip text
                 miniwin.cursor_hand,        -- hand cursor
                 0)                          -- flags
Lua notes
The handler function names can be omitted and default to the empty string (ie. no function).
The Cursor and Flags arguments are optional and default to zero.

You can use the following constants for the cursor:

miniwin.cursor_none = -1
miniwin.cursor_arrow = 0
miniwin.cursor_hand = 1
miniwin.cursor_ibeam = 2
miniwin.cursor_plus = 3
miniwin.cursor_wait = 4
miniwin.cursor_up = 5
miniwin.cursor_nw_se_arrow = 6
miniwin.cursor_ne_sw_arrow = 7
miniwin.cursor_ew_arrow = 8
miniwin.cursor_ns_arrow = 9
miniwin.cursor_both_arrow = 10
miniwin.cursor_x = 11
miniwin.cursor_help = 12


You can use the following constants for the flags:

miniwin.hotspot_report_all_mouseovers = 1


In the callback functions (called on mousedown etc.) you can use the following constants for the flags (first argument to the callback):

miniwin.hotspot_got_shift = 1
miniwin.hotspot_got_control = 2
miniwin.hotspot_got_alt = 4
miniwin.hotspot_got_lh_mouse = 16
miniwin.hotspot_got_rh_mouse = 32
miniwin.hotspot_got_dbl_click = 64
miniwin.hotspot_got_not_first = 128
miniwin.hotspot_got_middle_mouse = 512

miniwin.wheel_got_shift = 1         
miniwin.wheel_got_control = 2
miniwin.wheel_got_alt = 4
miniwin.wheel_scroll_back = 256
Returns eNoSuchWindow - no such miniwindow
eInvalidObjectLabel - one of the script functions is not a valid function name
eHotspotPluginChanged - the plugin is not the same one as used before for hotspots
eItemInUse - attempt to add a hotspot in the middle of adding a hotspot
eOK - completed OK

View list of return code meanings

Introduced in version 4.34

See also ...

Function Description
WindowCreate Creates a miniwindow
WindowDeleteAllHotspots Deletes all hotspots from a miniwindow
WindowDeleteHotspot Deletes a hotspot from a miniwindow
WindowDragHandler Adds a drag handler to a miniwindow hotspot
WindowHotspotInfo Returns information about a hotspot
WindowHotspotList Lists all hotspots installed into a miniwindow
WindowHotspotTooltip Changes the tooltip text for a hotspot in a miniwindow
WindowMoveHotspot Moves a hotspot in a miniwindow

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.


Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes


Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes


View all functions

[Back]

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]