Script function

world.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);

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.

Available in MUSHclient 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
  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

See Also ...

Topic

MiniWindows

Functions

(GetDeviceCaps) Gets screen device capabilities
(SetCursor) Changes the shape of the mouse cursor
(TextRectangle) Specifies the size of the rectangle in which text is displayed in the output window.
(WindowAddHotspot) Adds a hotspot to a miniwindow
(WindowArc) Draws an arc in a miniwindow
(WindowBezier) Draws a Bézier curve in a miniwindow
(WindowBlendImage) Blends an image into a miniwindow, using a specified blending mode
(WindowCircleOp) Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow
(WindowCreate) Creates a miniwindow
(WindowCreateImage) Creates an image in a miniwindow
(WindowDelete) Deletes a miniwindow
(WindowDeleteAllHotspots) Deletes all hotspots from a miniwindow
(WindowDeleteHotspot) Deletes a hotspot from a miniwindow
(WindowDrawImage) Draws an image into a miniwindow
(WindowDrawImageAlpha) Draws an image into a miniwindow respecting the alpha channel
(WindowFilter) Performs a filtering operation over part of the miniwindow.
(WindowFont) Loads a font into a miniwindow
(WindowFontInfo) Returns information about a font
(WindowFontList) Lists all fonts loaded into a miniwindow
(WindowGetImageAlpha) Draws the alpha channel of an image into a miniwindow
(WindowGetPixel) Gets the colour of a single pixel in a miniwindow
(WindowGradient) Draws a gradient in a rectangle
(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
(WindowImageFromWindow) Creates an image from another miniwindow
(WindowImageInfo) Returns information about an image
(WindowImageList) Lists all images installed into a miniwindow
(WindowImageOp) Draws an ellipse, rectangle or round rectangle, filled with an image
(WindowInfo) Returns information about a miniwindow
(WindowLine) Draws a line in a miniwindow
(WindowList) Lists all miniwindows
(WindowLoadImage) Loads an image into a miniwindow from a disk file
(WindowMenu) Creates a pop-up menu inside a miniwindow
(WindowMergeImageAlpha) Merges an image into a miniwindow based on an alpha mask
(WindowMoveHotspot) Moves a hotspot in a miniwindow
(WindowPolygon) Draws a polygon in a miniwindow
(WindowPosition) Moves a miniwindow
(WindowRectOp) Draws a rectangle in a miniwindow
(WindowResize) Resizes a miniwindow
(WindowScrollwheelHandler) Adds a scroll-wheel handler to a miniwindow hotspot
(WindowSetPixel) Sets a single pixel in a miniwindow to the specified colour
(WindowSetZOrder) Sets the Z-Order for a miniwindow
(WindowShow) Shows or hides a miniwindow
(WindowText) Draws text into a miniwindow
(WindowTextWidth) Calculates the width of text in a miniwindow
(WindowTransformImage) Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing
(WindowWrite) Writes the contents of a miniwindow to disk as a graphics file

(Help topic: function=WindowDragHandler)