world.WindowDragHandler

MUSHclient script function (Method) — introduced in version 4.40

Adds a drag handler to a miniwindow hotspot

Prototype

long WindowDragHandler(BSTR WindowName, BSTR HotspotId, BSTR MoveCallback, BSTR ReleaseCallback, long Flags);

Data type meanings

Description

Adds drag handler callbacks to the nominated hotspot.

If:

* 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:

http://www.gammon.com.au/forum/?id=9254

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.

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
  else
    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

Return value

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

Return code meanings

Related topic

MiniWindows

See also