MUSHclient documentation: WindowDragHandler

WindowDragHandler

WindowDragHandler
Script function world.WindowDragHandler Read about scripting Type Method Summary Adds a drag handler to a miniwindow hotspot Prototype `long WindowDragHandler(BSTR Name, BSTR HotspotId, BSTR MoveCallback, BSTR ReleaseCallback, long Flags);` View list of 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 This create a hotspot in the miniwindow, and remembers it by the nominated "hotspot id". Name - the name of an existing miniwindow. HotspotId - the hotspot id of an existing hotspot. MoveCallback - the script function to be called when you move the mouse ReleaseCallback - 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 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. 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.` 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` View list of return code meanings See Also ... Topic Mini Windows 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) 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) WindowPolygon (Draws a polygon in a miniwindow) WindowPosition (Moves a miniwindow) WindowRectOp (Draws a rectangle in a miniwindow) WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour) WindowShow (Shows or hides a miniwindow) WindowText (Draws text into a miniwindow) WindowTextWidth (Calculates the width of text in a miniwindow) WindowWrite (Writes the contents of a miniwindow to disk as a graphics file) (Help topic: function=WindowDragHandler) Documentation contents page

Script function

world.WindowDragHandler

Read about scripting

Type

Method

Summary

Adds a drag handler to a miniwindow hotspot

Prototype

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

View list of 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



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



Name - the name of an existing miniwindow.



HotspotId - the hotspot id of an existing hotspot.



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



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



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.

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.

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