MUSHclient documentation: WindowMenu

WindowMenu

WindowMenu
Script function world.WindowMenu Read about scripting Type Method Summary Creates a pop-up menu inside a miniwindow Prototype `BSTR WindowMenu(BSTR Name, long Left, long Top, BSTR Items);` View list of data type meanings Description This creates a pop-up menu inside a miniwindow. This is intended to let you click on an item (for example, a piece of inventory), and select "take/drop/equip/wield" and so on. The window must exist, and be visible, or an empty string is returned. Name: The name of an existing miniwindow Left: The X position inside the miniwindow Top: The Y position inside the miniwindow Items: A string containing the menu items to be displayed, see below. The X and Y position must be inside the miniwindow (ie. not negative, and not exceeding the miniwindow's defined width and height). Otherwise, an empty string is returned. You can use WindowInfo (win, 14) and WindowInfo (win, 15) to find where the mouse was last clicked inside this miniwindow. The Items parameter is a string, containing the menu items to be displayed, separated by the "\|" character. Leading and trailing spaces are removed from each item. For example: Item = "^Sword \| - \| Wield \| Equip \| - \| Take \| Drop " There must be at least one item, or an empty string is returned. An item which is empty, or consisting of the character "-" is displayed as a menu separator (horizontal line). An item which commences with the "^" character is displayed disabled (grayed out, and it cannot be selected). The "^" character is removed. You can display a maximum of 30 selectable items. The return value is the selected item, if any. If no item is selected (ie. the menu is dismissed) then an empty string will be returned. In the above example, a menu would be shown like this: Sword (grayed out) ----- Wield Equip ----- Take Drop Thus the return value would be one of: "" - menu dismissed "Wield", "Equip", "Take", or "Drop" Note that the leading and trailing spaces around the items have been removed in the return value. WARNING - we reserve non alpha-numeric characters in the first position of each item for future expansion. For example, perhaps in future versions "Equip" might be used to tick the Equip item. SUGGESTION - we strongly recommend that, if you are creating a menu in response to a mouse-click, you do it on the "mouse up" rather than "mouse down". The reason for this is that MUSHclient tracks mouse-down events and their corresponding mouse-up events, in order to call the appropriate hotspot routines (mouse-down, mouse-up, mouse-down cancel). However if you call WindowMenu in response to a mouse-down, the next mouse-up is "swallowed" up by the menu handler, and thus MUSHclient doesn't "see" it. The end result is that MUSHclient thinks the mouse is down, when it is in fact, up. This gets the hotspot events out of synchronization, and then subsequent things like mouse-overs are not processed correctly. So, for best results, draw a menu after a mouse-up. This if in fact what most Windows programs do, if you look carefully. In general, programs don't respond when you click down on the mouse, the action response happens when you let go (the mouse-up event). Lua example* `result = WindowMenu (win, WindowInfo (win, 14), -- x WindowInfo (win, 15), -- y "^Sword of Fire\|-\|Wield\|Drop\|Wear") if result ~= "" then Send (result .. " 'Sword of Fire') end -- if` Return value `If there was an error condition as described above, the empty string. If the menu was dismissed, or no item selected, the empty string. Otherwise, the text of the selected item, with leading and trailing spaces removed.` 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) 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) 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) 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=WindowMenu) Documentation contents page

Script function

world.WindowMenu

Read about scripting

Type

Method

Summary

Creates a pop-up menu inside a miniwindow

Prototype

BSTR WindowMenu(BSTR Name, long Left, long Top, BSTR Items);

View list of data type meanings

Description

This creates a pop-up menu inside a miniwindow. This is intended to let you click on an item (for example, a piece of inventory), and select "take/drop/equip/wield" and so on.



The window must exist, and be visible, or an empty string is returned.





Name: The name of an existing miniwindow



Left: The X position inside the miniwindow



Top: The Y position inside the miniwindow



Items: A string containing the menu items to be displayed, see below.





The X and Y position must be inside the miniwindow (ie. not negative, and not exceeding the miniwindow's defined width and height). Otherwise, an empty string is returned.



You can use WindowInfo (win, 14) and WindowInfo (win, 15) to find where the mouse was last clicked inside this miniwindow.



The Items parameter is a string, containing the menu items to be displayed, separated by the "|" character. Leading and trailing spaces are removed from each item.



For example:  Item = "^Sword | - | Wield | Equip | - |  Take | Drop "



There must be at least one item,  or an empty string is returned.



An item which is empty, or consisting of the character "-" is displayed as a menu separator (horizontal line).



An item which commences with the "^" character is displayed disabled (grayed out, and it cannot be selected). The "^" character is removed.



You can display a maximum of 30 selectable items.



The return value is the selected item, if any. If no item is selected (ie. the menu is dismissed) then an empty string will be returned.



In the above example, a menu would be shown like this:



Sword (grayed out)

-----

Wield

Equip

-----

Take

Drop



Thus the return value would be one of:



"" - menu dismissed

"Wield", "Equip", "Take", or "Drop"



Note that the leading and trailing spaces around the items have been removed in the return value.



WARNING - we reserve non alpha-numeric characters in the first position of each item for future expansion. For example, perhaps in future versions "*Equip" might be used to tick the Equip item.



SUGGESTION - we strongly recommend that, if you are creating a menu in response to a mouse-click, you do it on the "mouse up" rather than "mouse down".



The reason for this is that MUSHclient tracks mouse-down events and their corresponding mouse-up events, in order to call the appropriate hotspot routines (mouse-down, mouse-up, mouse-down cancel). 



However if you call WindowMenu in response to a mouse-down, the next mouse-up is "swallowed" up by the menu handler, and thus MUSHclient doesn't "see" it. The end result is that MUSHclient thinks the mouse is down, when it is in fact, up. This gets the hotspot events out of synchronization, and then subsequent things like mouse-overs are not processed correctly.



So, for best results, draw a menu after a mouse-up. This if in fact what most Windows programs do, if you look carefully. In general, programs don't respond when you click down on the mouse, the action response happens when you let go (the mouse-up event).

Lua example

result = WindowMenu (win, 
  WindowInfo (win, 14),  -- x
  WindowInfo (win, 15),   -- y
  "^Sword of Fire|-|Wield|Drop|Wear")

if result ~= "" then
  Send (result .. " 'Sword of Fire')
end -- if

Return value

If there was an error condition as described above, the empty string.

If the menu was dismissed, or no item selected, the empty string.

Otherwise, the text of the selected item, with leading and trailing spaces removed.

See Also ...

Topic