MUSHclient documentation: function WindowAddHotspot

Log on

WindowAddHotspot

WindowAddHotspot
Script function world.WindowAddHotspot Read about scripting Type Method Summary Adds a hotspot to a miniwindow Prototype `long WindowAddHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom, BSTR MouseOver, BSTR CancelMouseOver, BSTR MouseDown, BSTR CancelMouseDown, BSTR MouseUp, BSTR TooltipText, long Cursor, long Flags);` View list of data type meanings Description 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 "callbacks" - that is, when you mouse over a hotspot, a function in your main script file, or plugin, is called (if you nominate 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. WARNING: If you set the "draw underneath" flag when calling WindowCreate, then you cannot use hotspots, as the hotspots are underneath the text and will not be detected. WARNING: If you set the "ignore mouse" flag when calling WindowCreate, then you cannot use hotspots, as mouse clicks and movement will not be detected. If you want to handle dragging (moving the mouse after clicking), see also WindowDragHandler. For more information, see: http://www.gammon.com.au/mushclient/mw_hotspots.htm This create a hotspot in the miniwindow, and remembers it by the nominated "hotspot id". WindowName - the name of an existing miniwindow. Names are case-sensitive. HotspotId - the hotspot id to be associated with this particular hotspot. Hotspot IDs are case-sensitive. Left, Top, Right, Bottom - describes the hotspot rectangle. MouseOver - the name of the script function to be called when you mouse over the hotspot rectangle CancelMouseOver - the name of the script function to be called when you move the mouse away from the hotspot rectangle MouseDown - the name of the script function to be called when you mouse down in the hotspot rectangle CancelMouseDown - the name of the script function to be called when you release the mouse not in the hotspot rectangle that the mouse-down occurred in MouseUp - the name of the script function to be called when you release the mouse in the hotspot rectangle that the mouse-down occurred in TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text. To change a tooltip later, see: WindowHotspotTooltip Cursor - a number which indicates what shape the mouse pointer is to take when over the hotspot, as follows: -1: no cursor 0: arrow 1: hand 2: I-beam 3: + symbol 4: wait (hour-glass) 5: up arrow 6: arrow nw-se 7: arrow ne-sw 8: arrow e-w 9: arrow n-s 10: arrow - all ways 11: (X) cannot do action 12: help (? symbol) Flags - flags to modify hotspot behaviour. These should be or'd together. 0x01 : All mouse-over events are reported to the mouseover callback (if any) For subsequent mouse-overs within a single hotspot the flags will have the 0x80 bit set. For the first mouse-over the 0x80 bit will be clear. The callback functions 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: 0x01 - Shift key down 0x02 - Control key down 0x04 - Alt key down 0x10 - LH mouse 0x20 - RH mouse 0x40 - double-click 0x80 - mouse-over not first time 0x100 - scroll wheel scrolled (towards you) 0x200 - middle mouse 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) You could test this in Lua like this: if bit.band (flags, 0x20) ~= 0 then -- mouse be RH mouse end -- if WARNING: The hotspot 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. WARNING: The hotspot callbacks have to be in the same script space as each other (either all in the same plugin, or the world script file). Available in MUSHclient version 4.34 onwards. Lua example `WindowAddHotspot(win, "hs1", 10, 10, 60, 20, -- rectangle "mouseover", "cancelmouseover", "mousedown", "cancelmousedown", "mouseup", "Click here to be healed", -- tooltip text miniwin.cursor_hand, -- hand cursor 0) -- flags` Lua notes The handler function names can be omitted and default to the empty string (ie. no function). The Cursor and Flags arguments are optional and default to zero. You can use the following constants for the cursor: miniwin.cursor_none = -1 miniwin.cursor_arrow = 0 miniwin.cursor_hand = 1 miniwin.cursor_ibeam = 2 miniwin.cursor_plus = 3 miniwin.cursor_wait = 4 miniwin.cursor_up = 5 miniwin.cursor_nw_se_arrow = 6 miniwin.cursor_ne_sw_arrow = 7 miniwin.cursor_ew_arrow = 8 miniwin.cursor_ns_arrow = 9 miniwin.cursor_both_arrow = 10 miniwin.cursor_x = 11 miniwin.cursor_help = 12 You can use the following constants for the flags: miniwin.hotspot_report_all_mouseovers = 1 In the callback functions (called on mousedown etc.) you can use the following constants for the flags (first argument to the callback): miniwin.hotspot_got_shift = 1 miniwin.hotspot_got_control = 2 miniwin.hotspot_got_alt = 4 miniwin.hotspot_got_lh_mouse = 16 miniwin.hotspot_got_rh_mouse = 32 miniwin.hotspot_got_dbl_click = 64 miniwin.hotspot_got_not_first = 128 miniwin.hotspot_got_middle_mouse = 512 miniwin.wheel_got_shift = 1 miniwin.wheel_got_control = 2 miniwin.wheel_got_alt = 4 miniwin.wheel_scroll_back = 256 Return value `eNoSuchWindow - no such miniwindow 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 eItemInUse - attempt to add a hotspot in the middle of adding a hotspot eOK - completed OK` View list of return code meanings 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. (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 (WindowDragHandler) Adds a drag handler to a miniwindow hotspot (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=WindowAddHotspot)

Script function

world.WindowAddHotspot

Read about scripting

Type

Method

Summary

Adds a hotspot to a miniwindow

Prototype

long WindowAddHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom, BSTR MouseOver, BSTR CancelMouseOver, BSTR MouseDown, BSTR CancelMouseDown, BSTR MouseUp, BSTR TooltipText, long Cursor, long Flags);

View list of data type meanings

Description

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 "callbacks" - that is, when you mouse over a hotspot, a function in your main script file, or plugin, is called (if you nominate 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. WARNING: If you set the "draw underneath" flag when calling WindowCreate, then you cannot use hotspots, as the hotspots are underneath the text and will not be detected. WARNING: If you set the "ignore mouse" flag when calling WindowCreate, then you cannot use hotspots, as mouse clicks and movement will not be detected. If you want to handle dragging (moving the mouse after clicking), see also WindowDragHandler. For more information, see: http://www.gammon.com.au/mushclient/mw_hotspots.htm This create a hotspot in the miniwindow, and remembers it by the nominated "hotspot id". WindowName - the name of an existing miniwindow. Names are case-sensitive. HotspotId - the hotspot id to be associated with this particular hotspot. Hotspot IDs are case-sensitive. Left, Top, Right, Bottom - describes the hotspot rectangle. MouseOver - the name of the script function to be called when you mouse over the hotspot rectangle CancelMouseOver - the name of the script function to be called when you move the mouse away from the hotspot rectangle MouseDown - the name of the script function to be called when you mouse down in the hotspot rectangle CancelMouseDown - the name of the script function to be called when you release the mouse not in the hotspot rectangle that the mouse-down occurred in MouseUp - the name of the script function to be called when you release the mouse in the hotspot rectangle that the mouse-down occurred in TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text. To change a tooltip later, see: WindowHotspotTooltip Cursor - a number which indicates what shape the mouse pointer is to take when over the hotspot, as follows: -1: no cursor 0: arrow 1: hand 2: I-beam 3: + symbol 4: wait (hour-glass) 5: up arrow 6: arrow nw-se 7: arrow ne-sw 8: arrow e-w 9: arrow n-s 10: arrow - all ways 11: (X) cannot do action 12: help (? symbol) Flags - flags to modify hotspot behaviour. These should be or'd together. 0x01 : All mouse-over events are reported to the mouseover callback (if any) For subsequent mouse-overs within a single hotspot the flags will have the 0x80 bit set. For the first mouse-over the 0x80 bit will be clear. The callback functions 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: 0x01 - Shift key down 0x02 - Control key down 0x04 - Alt key down 0x10 - LH mouse 0x20 - RH mouse 0x40 - double-click 0x80 - mouse-over not first time 0x100 - scroll wheel scrolled (towards you) 0x200 - middle mouse 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) You could test this in Lua like this: if bit.band (flags, 0x20) ~= 0 then -- mouse be RH mouse end -- if WARNING: The hotspot 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. WARNING: The hotspot callbacks have to be in the same script space as each other (either all in the same plugin, or the world script file).

Available in MUSHclient version 4.34 onwards.

Lua example

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

Lua notes

The handler function names can be omitted and default to the empty string (ie. no function).
The Cursor and Flags arguments are optional and default to zero.

You can use the following constants for the cursor:

miniwin.cursor_none = -1
miniwin.cursor_arrow = 0
miniwin.cursor_hand = 1
miniwin.cursor_ibeam = 2
miniwin.cursor_plus = 3
miniwin.cursor_wait = 4
miniwin.cursor_up = 5
miniwin.cursor_nw_se_arrow = 6
miniwin.cursor_ne_sw_arrow = 7
miniwin.cursor_ew_arrow = 8
miniwin.cursor_ns_arrow = 9
miniwin.cursor_both_arrow = 10
miniwin.cursor_x = 11
miniwin.cursor_help = 12


You can use the following constants for the flags:

miniwin.hotspot_report_all_mouseovers = 1


In the callback functions (called on mousedown etc.) you can use the following constants for the flags (first argument to the callback):

miniwin.hotspot_got_shift = 1
miniwin.hotspot_got_control = 2
miniwin.hotspot_got_alt = 4
miniwin.hotspot_got_lh_mouse = 16
miniwin.hotspot_got_rh_mouse = 32
miniwin.hotspot_got_dbl_click = 64
miniwin.hotspot_got_not_first = 128
miniwin.hotspot_got_middle_mouse = 512

miniwin.wheel_got_shift = 1         
miniwin.wheel_got_control = 2
miniwin.wheel_got_alt = 4
miniwin.wheel_scroll_back = 256

Return value

eNoSuchWindow - no such miniwindow 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 eItemInUse - attempt to add a hotspot in the middle of adding a hotspot eOK - completed OK

View list of return code meanings

See Also ...

Topic

MiniWindows

Functions

(Help topic: function=WindowAddHotspot)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.