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

Miniwindows in MUSHclient - Hotspots

Written by Nick Gammon - July 2008. Updated September 2010.

On this page:

See also:

Hotspots

In order to allow you to interact with the miniwindows, you can designate hotspots (really, "hot rectangles"). When the mouse is moved inside these designated areas (of which there can be any number per miniwindow), script functions in your plugin can be called. These functions can handle:

In addition, you can specify tooltip text, which automatically appears if the mouse hovers over a hotspot, after a short delay. This can be used to provide short help messages.

You can also add support for mouse dragging (from version 4.40 onwards) using WindowDragHandler, and for the player moving the mouse scroll-wheel with WindowScrollwheelHandler.


Add a hotspot

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 plugin "callbacks" - that is, when you mouse over a hotspot, a function in your plugin is called (if you nominate one). Thus hotspots would generally be implemented inside plugins.

In addition to the callbacks defined here, you can also use WindowDragHandler to add callbacks for dragging with the mouse, and WindowScrollwheelHandler for if the scroll-wheel on the mouse is moved.

WindowAddHotspot function prototype:

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

Example of making a hotspot


WindowAddHotspot(win, "hs1",  
                 10, 10, 60, 20,   -- rectangle
                 "mouseover", 
                 "cancelmouseover", 
                 "mousedown",
                 "cancelmousedown", 
                 "mouseup", 
                 "Click here to be healed",  -- tooltip text
                 miniwin.cursor_hand, 0)  -- hand cursor

Hotspot callback functions

The functions specified for WindowAddHotspot do not have to exist - use an empty string if you don't want a particular action to cause a function call. However if the callback function name is not empty it must be a valid function name. There is no error message if the function cannot be found, however if you turn Trace on (Game menu -> Trace) then messages will appear in the output window to warn you about missing (non-empty) functions.

The callback function 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:

ValuePurposeLua symbol
0x01 (1) Shift key down miniwin.hotspot_got_shift
0x02 (2) Control key down miniwin.hotspot_got_control
0x04 (4) Alt key down miniwin.hotspot_got_alt
0x10 (16) LH mouse miniwin.hotspot_got_lh_mouse
0x20 (32) RH mouse miniwin.hotspot_got_rh_mouse
0x40 (64) Double-click miniwin.hotspot_got_dbl_click
0x80 (128) Not first mouse-over in hotspot miniwin.hotspot_got_not_first
0x100 (256) Scroll wheel scrolled down (towards you) miniwin.wheel_scroll_back

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)
-- that is:
flags = miniwin.hotspot_got_shift + miniwin.hotspot_got_control + 
        miniwin.hotspot_got_lh_mouse + miniwin.hotspot_got_dbl_click
        
-- in Lua you might test for a LH mouse click like this:

if bit.band (flags, miniwin.hotspot_got_lh_mouse) ~= 0 then
  -- LH mouse clicked
end -- if

Sequence of callback function calls

Mouse over

If the mouse moves over a hotspot, after about half a second the TooltipText string is displayed in a tooltip window (if any is specified). This tool tip will disappear after a few seconds.

The moment the mouse moves over a hotspot the mouse cursor is changed to be the shape specified for the hotspot (Cursor argument).

Suggestions

The MouseOver event (with the corresponding CancelMouseOver where required) can be used to:

The CancelMouseOver event should be used, if necessary to:

Mouse down

Suggestions

The MouseDown event (with the corresponding CancelMouseOver or MouseUp where required) can be used to:

The CancelMouseDown event should be used, if necessary to:

The MouseUp event should be used, if necessary to:


Delete a hotspot

If you no longer require a hotspot it can be deleted by calling WindowDeleteHotspot.

WindowDeleteHotspot function prototype:

This deletes the hotspot from the miniwindow.

Example of deleting a hotspot


WindowDeleteHotspot (win, "hs1");

Delete all hotspots

If you no longer require your hotspots (perhaps after clearing the window and starting again), you can call WindowDeleteAllHotspots.

WindowDeleteAllHotspots function prototype:

This deletes all hotspots from the miniwindow.

Example of deleting all hotspots


WindowDeleteAllHotspots (win);

Note - when WindowCreate is called, all existing hotspots are automatically deleted, if the window previously existed, unless the flag miniwin.create_keep_hotspots was used when calling WindowCreate.


Move a hotspot

If you need to move a hotspot around you can do it with WindowMoveHotspot.

WindowMoveHotspot function prototype:

This moves a hotspot from one place to another. You might use this in a resize callback function.

Example of moving a hotspot


WindowMoveHotspot (win, "hs1", 20, 20, 40, 40);

List all hotspots

WindowHotspotList function prototype:

This returns a list of all hotspots loaded into this miniwindow. You could use this to find which hotspots have been created, and then use WindowHotspotInfo to find information about each one.

Example:


Get information about a hotspot

WindowHotspotInfo function prototype:

This returns information about a hotspot. You need to specify the name of the miniwindow, and the hotspot id you used when creating the hotspot.


Change the tooltip text for a hotspot

WindowHotspotTooltip function prototype:

This changes the tooltip text for a hotspot (shown if the mouse hovers over the hotspot for a second or so).


Example of adding a hotspot

With the above code in place, you see the "?" characters in the specified locations. These are the hyperlinks:

Now if you click on one, it opens the colour picker, so you can choose the colour you want:


Set up a mouse-drag handler

WindowDragHandler function prototype:

This adds a "mouse drag handler" to the designated hotspot. You need to specify the name of the miniwindow, and the hotspot id you used when creating the hotspot. This provides extra functionality which applies after there is a mouse-down in that hotspot.

The flags passed to the drag handler will be a bit mask as follows:

ValuePurposeLua symbol
0x01 (1) Shift key down miniwin.drag_got_shift
0x02 (2) Control key down miniwin.drag_got_control
0x04 (4) Alt key down miniwin.drag_got_alt

Example of adding a drag handler


Set up a scroll-wheel handler

WindowScrollwheelHandler function prototype:

Adds a scroll-wheel handler callback to the nominated hotspot. If:

... then the callback function is called.

The callback function should look like this:


function wheel_move (flags, hotspot_id)

  if bit.band (flags, miniwin.wheel_scroll_back) ~= 0 then
    -- wheel scrolled down (towards you)
  else
    -- wheel scrolled up (away from you)
  end -- if

  return 0  -- needed for some languages
end -- wheel_move

Since the hotspot ID is passed to the callback function, you can share the same function amongst all your hotspots.

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 passed to the move function is a bit mask as follows:

ValuePurposeLua symbol
0x01 (1) Shift key down miniwin.wheel_got_shift
0x02 (2) Control key down miniwin.wheel_got_control
0x04 (4) Altkey down miniwin.wheel_got_alt
0x100 (256) Scroll wheel scrolled down (towards you) miniwin.wheel_scroll_back


Other pages about miniwindows


[Home]

Written by Nick Gammon - 5K

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

[Best viewed with any browser - 2K]    [Internet Contents Rating Association (ICRA) - 2K]    [Web site powered by FutureQuest.Net]