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

MUSHclient scripting

Description of MUSHclient world function: world.WindowDragHandler

Name WindowDragHandler
Type Method
Summary Adds a drag handler to a miniwindow hotspot
Prototype long WindowDragHandler(BSTR WindowName, BSTR HotspotId, BSTR MoveCallback, BSTR ReleaseCallback, long Flags);

View list of data type meanings


Adds drag handler callbacks to the nominated hotspot.


* The user clicks in the hotspot; and
* Moves the mouse; and
* There is a MoveCallback function defined (by using this function)

... then the callback function is called every time the mouse moves (regardless of whether it is still over the current miniwindow).

Also, when the mouse is eventually released, the ReleaseCallback function is called. Unlike the existing mousedown and mouseup functions, these two functions are called no matter where the mouse is - it doesn't even have to be over the MUSHclient window.

This lets you do things like move a window around (eg. drag its title bar), or drag something from one window to another.

There are now WindowInfo selectors (17 and 18) which return the current position of the mouse in "client" coordinates. That is, relative to the output window, not relative to the miniwindow. The mouse position in client coordinates could be used to work out where in the output window the mouse is.

For each miniwindow, WindowInfo selectors 10 to 13 give the current position of that miniwindow (as last drawn), and thus you can work out whether the cursor is over a particular 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.

If you want to change the shape of the cursor as the mouse is being dragged, see SetCursor.

For more information, see:


WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id of an existing hotspot.

MoveCallback - the name of the script function to be called when you move the mouse

ReleaseCallback - the name of the script function to be called when you release the mouse

Flags - flags to modify dragging behaviour. Leave as zero, these are not currently used.

To cancel a drag handler, just set the function names to empty strings, eg.

WindowDragHandler(win, "hs1", "", "", 0)

The callback functions should look like this:

function drag_move (flags, hotspot_id)

-- find where it is now
local posx = WindowInfo (win, 17) -- where mouse is relative to output window (X)
local posy = WindowInfo (win, 18) -- where mouse is relative to output window (Y)

-- reposition window here

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

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 (from mouse-down)
0x20 - RH mouse (from mouse-down)
0x40 - double-click (from mouse-down)

Note that the mouse was not necessarily clicked on the top-left corner of the miniwindow. Thus a mousedown handler should remember the offset from the edge of the miniwindow when the mouse is clicked (WindowInfo selectors 14 and 15). Then to reposition the window (if that is what you are trying to do) you need to subtract that offset from the values returned by WindowInfo selectors 17 and 18, to get the new location for the top-left corner.

See the example below in the Lua section for more details.

WARNING: The 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.

Note: Available in version 4.40 onwards.

Lua example
-- mouse down function - remember how far in from edge of window mouse was

function mousedown(flags, hotspot_id)
  startx, starty = WindowInfo (win, 14), WindowInfo (win, 15)
end -- mousedown

-- mouse release function - do something useful at the destination location

function dragrelease(flags, hotspot_id)
  print ("mouse drag release for " .. hotspot_id)
  print ("released at position", WindowInfo (win, 17), WindowInfo (win, 18))
end -- dragrelease

function dragmove(flags, hotspot_id)
  print ("moved to position", WindowInfo (win, 17), WindowInfo (win, 18))
  local posx, posy = WindowInfo (win, 17),
                     WindowInfo (win, 18)
  -- move the window to the new location
  WindowPosition(win, posx - startx, posy - starty, 0, 2);
  -- change the mouse cursor shape appropriately
  if posx < 0 or posx > GetInfo (281) or
     posy < 0 or posy > GetInfo (280) then
    check (SetCursor ( 11))   -- X cursor
    check (SetCursor ( 1))   -- hand cursor
  end -- if
end -- dragmove

-- set up the drag handler
WindowDragHandler (win, "hs1", "dragmove", "dragrelease", 0)
Lua notes
The two handler function names can be omitted and default to the empty string (ie. no function).

Flags can be omitted and default to zero.

You can use the following constants for the flags parameter (first parameter) to the callback function called when the mouse is moved or released.

miniwin.drag_got_shift = 1
miniwin.drag_got_control = 2
miniwin.drag_got_alt = 4
miniwin.hotspot_got_lh_mouse = 16
miniwin.hotspot_got_rh_mouse = 32
miniwin.hotspot_got_dbl_click = 64
Returns eNoSuchWindow - no such miniwindow
eHotspotNotInstalled - no such hotspot
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
eOK - completed OK

View list of return code meanings

Introduced in version 4.40

See also ...

Function Description
SetCursor Changes the shape of the mouse cursor
WindowAddHotspot Adds a hotspot to a miniwindow
WindowCreate Creates a miniwindow
WindowDeleteAllHotspots Deletes all hotspots from a miniwindow
WindowDeleteHotspot Deletes a hotspot from a miniwindow
WindowHotspotInfo Returns information about a hotspot
WindowHotspotList Lists all hotspots installed into a miniwindow
WindowScrollwheelHandler Adds a scroll-wheel handler to a miniwindow hotspot

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


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.


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]